Adobe Commerce (Magento)

Intégration Magento (Adobe Commerce) pour ajouter des boutons « Ajouter à Wallet » Apple Wallet et Google Wallet dans Mon compte pour les cartes de fidélité et les cartes-cadeaux.

Cette intégration explique comment ajouter un bouton unique « Add to Wallet » vers le Mon compte zone dans Adobe Commerce (Magento 2). Cette intégration Magento Apple Wallet / Google Wallet aide les clients à enregistrer une carte de fidélité ou d’adhésion (et éventuellement une carte-cadeau Wallet) directement dans leur portefeuille mobile, à l’aide d’un identifiant disponible dans la session client Adobe Commerce.

Adobe Commerce My Account page showing an “Add to Wallet” button.

Exemples concrets

Un programme de fidélité affiche « Add to Wallet » à côté du numéro d’adhésion dans Mon compte.
Un programme de carte-cadeau affiche un bouton « Add to Wallet » uniquement pour active les cartes-cadeaux.
Un parcours pick & collect affiche un CTA de carte de retrait sur une page de retrait dédiée, où une référence de retrait est disponible côté serveur.

Adobe Commerce et Magento Open Source partagent la même architecture de storefront Magento 2. Les schémas d’implémentation de cette page s’appliquent aux deux, avec de légères différences dans le déploiement et la configuration de sécurité.

Pour l’utilisation générique du SDK cinto (mode id de Carte, détection de plateforme, personnalisation du QR code sur ordinateur), voir Sur votre site web.

Fonctionnement

Le SDK cinto de The Wallet Crew affiche le CTA approprié selon l’appareil.

Sur iOS, le bouton télécharge une Carte Apple Wallet. Sur Android, il ouvre Google Wallet. Sur ordinateur, le SDK redirige vers une page de Carte hébergée qui peut être scannée ou ouverte sur mobile.

Dans cette configuration Adobe Commerce, la carte est récupérée à l’aide de :

Une type de Carte (exemple : utilisateur)
Un identifiant client Magento envoyé en tant que identifiant externe (exemple : magento.customer_Id)
Un HMAC signature qui prouve que l’identifiant a été émis par le backend de la marque

Le HMAC doit être calculé côté serveur. Il ne doit pas être généré dans le navigateur.

Prérequis

Un modèle de Carte et une émission de Carte déjà configurés dans The Wallet Crew.
L’identifiant du tenant The Wallet Crew disponible (utilisé par l’URL du script du SDK).
Un identifiant client stable disponible dans la session sur la page de compte. Cet identifiant est utilisé par The Wallet Crew pour récupérer ou créer la carte. Le nom de la clé d’identifiant (exemple : magento.customer_Id) est défini lors de l’intégration du projet.

Ajoutez le bouton à la page de compte client Adobe Commerce

Les pages du storefront Adobe Commerce sont construites à partir de layout XML et modèles PHTML. Le rendu du bouton depuis un bloc Magento conserve les secrets côté serveur et permet un échappement sûr des attributs HTML.

L’implémentation de référence ci-dessous ajoute le bouton à la page de tableau de bord client par défaut (customer/account).

Stocker le secret utilisé pour calculer HMAC

Le secret HMAC doit rester côté serveur. Deux options courantes sont utilisées dans les projets Adobe Commerce.

Option A (recommandée) : stocker les valeurs dans app/etc/env.php

Stockez les valeurs dans la configuration de déploiement afin qu’elles ne soient pas modifiables depuis l’Admin Adobe Commerce.

app/etc/env.php (exemple)

<?php
return [
    // ...
    'walletcrew' => [
        'tenant_id' => '<<tenantId>>',
        'hmac_secret' => '<<hmacSecret>>',
    ],
];

Option B : stocker le secret comme variable d’environnement

Cela maintient les secrets hors de la base de code et de la base de données. Cela fonctionne aussi bien avec les déploiements conteneurisés.

Variables d’environnement (exemple)

THEWALLETCREW_TENANT_ID=<<tenantId>>
THEWALLETCREW_HMAC_SECRET=<<hmacSecret>>

Dans Adobe Commerce Cloud, les variables d’environnement sont souvent utilisées comme source de vérité pour les secrets. Le app/etc/env.php fichier est généralement généré pendant le déploiement.

Il faut éviter de stocker le secret dans les fichiers de thème ou de le rendre dans le HTML. Seul le HMAC calculé doit parvenir au storefront.

Implémentation de référence (layout XML + bloc + PHTML)

Cette implémentation crée :

un Bloc classe qui lit l’ID client connecté et calcule le HMAC
un modèle PHTML qui affiche le chargeur du SDK + <div data-neostore-addToWalletButton ...>
un layout XML entrée qui insère le bloc dans le tableau de bord du compte client

Elle nécessite également une structure minimale de module pour qu’Adobe Commerce puisse charger les fichiers.

app/code/Vendor/WalletCrewCinto/registration.php

<?php
use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Vendor_WalletCrewCinto',
    __DIR__
);

app/code/Vendor/WalletCrewCinto/etc/module.xml

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_WalletCrewCinto" setup_version="1.0.0"/>
</config>

Une fois les fichiers déployés, activez le module et actualisez les fichiers générés et les caches.

Activer le module (exemple)

bin/magento module:enable Vendor_WalletCrewCinto
bin/magento setup:upgrade
bin/magento cache:flush

Ajoutez le layout XML sur le tableau de bord client

Ajoutez une mise à jour de layout pour injecter un bloc dans le conteneur de contenu du tableau de bord.

app/code/Vendor/WalletCrewCinto/view/frontend/layout/customer_account_index.xml

<?xml version="1.0"?>
<page xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="urn:magento:framework:View/Layout/etc/page_configuration.xsd">
    <body>
        <referenceContainer name="content">
            <block class="Vendor\WalletCrewCinto\Block\AddToWallet"
                   name="walletcrew.add_to_wallet"
                   template="Vendor_WalletCrewCinto::add-to-wallet.phtml"
                   cacheable="false"/>
        </referenceContainer>
    </body>
</page>

cacheable="false" garantit que les identifiants spécifiques au client ne sont pas mis en cache d’une session à l’autre.

Implémentez le bloc (calcul du HMAC côté serveur)

Le bloc lit l’ID du client connecté et calcule hash_hmac('sha256', $value, $secret).

app/code/Vendor/WalletCrewCinto/Block/AddToWallet.php

<?php
declare(strict_types=1);

namespace Vendor\WalletCrewCinto\Block;

use Magento\Customer\Model\Session as CustomerSession;
use Magento\Framework\App\DeploymentConfig;
use Magento\Framework\Escaper;
use Magento\Framework\View\Element\Template;

final class AddToWallet extends Template
{
    public function __construct(
        Template\Context $context,
        private readonly CustomerSession $customerSession,
        private readonly DeploymentConfig $deploymentConfig,
        private readonly Escaper $escaper,
        array $data = []
    ) {
        parent::__construct($context, $data);
    }

    public function getTenantId(): string
    {
        $fromEnvPhp = (string)($this->deploymentConfig->get('walletcrew/tenant_id') ?? '');
        if ($fromEnvPhp !== '') {
            return $fromEnvPhp;
        }

        return (string)(getenv('THEWALLETCREW_TENANT_ID') ?: getenv('WALLETCREW_TENANT_ID'));
    }

    public function getCustomerId(): ?string
    {
        $id = $this->customerSession->getCustomerId();
        return $id ? (string)$id : null;
    }

    public function getCustomerIdHmac(): ?string
    {
        $customerId = $this->getCustomerId();
        if ($customerId === null) {
            return null;
        }

        $secret = (string)($this->deploymentConfig->get('walletcrew/hmac_secret') ?? '');
        if ($secret === '') {
            $secret = (string)(getenv('THEWALLETCREW_HMAC_SECRET') ?: getenv('WALLETCREW_HMAC_SECRET'));
        }
        if ($secret === '') {
            return null;
        }

        return hash_hmac('sha256', $customerId, $secret);
    }

    public function escAttr(?string $value): string
    {
        return $this->escaper->escapeHtmlAttr((string)$value);
    }
}

Cet exemple utilise l’ID client Magento comme magento.customer_Id. Si un ID CRM est stocké sur l’entité client, il peut être utilisé à la place.

Rendre le bouton cinto dans un modèle PHTML

Le modèle injecte l’ID du tenant, l’ID client et le HMAC depuis le bloc.

app/code/Vendor/WalletCrewCinto/view/frontend/templates/add-to-wallet.phtml

<?php
/** @var \Vendor\WalletCrewCinto\Block\AddToWallet $block */
$tenantId = $block->getTenantId();
$customerId = $block->getCustomerId();
$hmac = $block->getCustomerIdHmac();

if (!$tenantId || !$customerId || !$hmac) {
    return;
}
?>

<script type="text/javascript">
(function (n, e, o) {
var s=n.createElement("script");s.src="https://sdk.neostore.cloud/scripts/"+e+"/cinto@1";s.async=1;
s.onload=function(){neostore.cinto.initialize(e,o)};n.body.appendChild(s);
})(document, "<?= $block->escAttr($tenantId) ?>", { language: "fr" });
</script>

<div data-neostore-addToWalletButton
     data-neostore-passType="user"
     data-neostore-externalIdentifiers-magento.customer_Id-value="<?= $block->escAttr($customerId) ?>"
     data-neostore-externalIdentifiers-magento.customer_Id-hmac="<?= $block->escAttr($hmac) ?>"
</div>

Si une autre langue est requise, mettez à jour { language: "fr" }. Si elle est omise, le SDK utilise la langue du navigateur.

La documentation complète du SDK cinto (options, solution de secours sur ordinateur et détection de plateforme) est disponible dans Sur votre site web.

Remarques sur le nom de l’identifiant externe

Les navigateurs mettent les attributs HTML en minuscules. Le SDK cinto inclut une règle d’échappement pour préserver les caractères majuscules en les précédant de _.

C’est pourquoi magento.customer_Id est écrit avec un soulignement avant I. Sans le soulignement, customer_Id serait interprété comme customerid.

Facultatif : liste blanche CSP Adobe Commerce

Certaines configurations Adobe Commerce imposent une Content Security Policy qui peut bloquer les scripts tiers par défaut. Si le script du SDK est bloqué, ajoutez à la liste blanche https://sdk.neostore.cloud.

La configuration CSP de Magento varie selon les versions et les configurations. Si CSP est activé, il faut l’aligner sur la stratégie CSP existante du projet.

Si le projet utilise le mécanisme de liste blanche CSP de Magento, autoriser l’hôte du SDK pour script-src suffit généralement.

app/code/Vendor/WalletCrewCinto/etc/csp_whitelist.xml (exemple)

<?xml version="1.0"?>
<csp_whitelist xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Csp:etc/csp_whitelist.xsd">
    <policies>
        <policy id="script-src">
            <values>
                <value id="walletcrew-sdk" type="host">https://sdk.neostore.cloud</value>
            </values>
        </policy>
    </policies>
</csp_whitelist>

Les projets Adobe Commerce centralisent souvent la gestion CSP (mode report-only vs mode appliqué). L’emplacement et le processus de liste blanche doivent correspondre aux conventions du projet.

Validez le résultat

La validation couvre généralement le rendu de la plateforme et l’installation de la Carte.

Sur iOS Safari, le CTA doit afficher Ajouter à Apple Wallet.
Sur Android Chrome, le CTA doit afficher Ajouter à Google Wallet.
Sur ordinateur, le CTA doit rediriger vers une page de Carte hébergée.
Après installation, la Carte doit être visible dans Apple Wallet ou Google Wallet.

Dépannage

Le bouton ne s’affiche pas

Les causes courantes sont un script SDK bloqué (CSP) ou un balisage manquant. Le HTML final doit contenir le chargeur du SDK cinto et le <div data-neostore-addToWalletButton ...> élément.

Cliquer sur le bouton provoque une erreur

Cela signifie généralement que l’identifiant externe ou le HMAC ne correspond pas à ce que The Wallet Crew attend. Vérifiez :

Le nom de la clé d’identifiant externe correspond à celui configuré pour Magento (exemple : magento.customer_Id).
Le HMAC a été calculé avec le bon secret du tenant et la valeur exacte de l’identifiant.

La mauvaise langue s’affiche

Définissez { language: "fr" } (ou un autre code langue ISO 639) dans les initialize() options.

FAQ

Cela nécessite-t-il un module personnalisé ?

Pas strictement. Une surcharge de thème peut suffire lorsque les valeurs côté serveur pour l’identifiant client et le HMAC peuvent être rendues. Un module personnalisé est généralement préférable car il garde le calcul du HMAC hors des modèles et centralise le chargement du secret (configuration de déploiement ou variables d’environnement).

Quel identifiant client faut-il utiliser ?

L’ID client interne d’Adobe Commerce est couramment utilisé car il est stable et toujours disponible sur la page de compte. Un projet peut aussi utiliser un ID CRM s’il est stocké sur l’entité client. L’identifiant doit rester stable dans le temps.

D’où vient le secret HMAC ?

Le HMAC est calculé avec un secret de tenant provenant de The Wallet Crew. Cela rend l’échange d’identifiant infalsifiable et empêche l’énumération. Le secret est généralement stocké dans la configuration de déploiement Adobe Commerce (app/etc/env.php) ou comme variable d’environnement et n’est jamais exposé au storefront.

La même approche peut-elle être utilisée pour les cartes-cadeaux ?

Oui. Le même modèle de carte-cadeau Wallet Magento fonctionne lorsque la carte-cadeau est émise comme type de carte dans The Wallet Crew et qu’un identifiant stable de carte-cadeau existe dans Adobe Commerce (ou dans un système connecté). La zone Mon compte peut afficher un bouton pour chaque carte-cadeau en remplaçant data-neostore-passType et la paire clé/valeur de l’identifiant externe vers l’identifiant de la carte-cadeau, puis en signant cet identifiant avec le HMAC côté serveur.

Comment gérer la rotation des secrets ?

Un plan de rotation utilise généralement une courte fenêtre de chevauchement. Pendant cette fenêtre, le backend peut accepter à la fois l’ancien et le nouveau secret pour la validation du HMAC. Après la fenêtre, seul le nouveau secret reste actif.

Le bouton peut-il être affiché ailleurs que sur la page de compte ?

Oui. Le même SDK peut être utilisé sur n’importe quelle page authentifiée où un identifiant stable est disponible côté serveur. Parmi les exemples courants figurent une page de liste de cartes-cadeaux, un tableau de bord de fidélité ou une page de retrait en magasin lorsqu’une carte de retrait est utilisée comme jeton de scan en magasin.

Mis à jour il y a 1 mois