Adobe Commerce (Magento)

Intégration Magento (Adobe Commerce) pour ajouter les 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 Wallet 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 réels

Un programme de fidélité affiche « Ajouter au Wallet » à côté du numéro d’adhésion dans Mon compte.
Un programme de carte-cadeau affiche un bouton « Ajouter au Wallet » uniquement pour carte-cadeau les cartes-cadeaux.
Un parcours click & collect affiche un CTA 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 boutique Magento 2. Les modèles d’implémentation présentés sur cette page s’appliquent aux deux, avec de légères différences de déploiement et de configuration de sécurité.

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

Comment ça marche

Le SDK cinto de The Wallet Crew affiche le bon CTA 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 prouvant 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 pendant l’onboarding du projet.

Ajoutez le bouton à la page de compte client Adobe Commerce

Les pages de la boutique Adobe Commerce sont construites à partir de XML de mise en page et modèles PHTML. Rendre le 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 par défaut du tableau de bord client (customer/account).

Stockez le secret utilisé pour calculer le HMAC

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

Option A (recommandée) : stockez 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 : stockez le secret comme variable d’environnement

Cela maintient les secrets hors du code source et hors de la base de données. Cela fonctionne également 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.

Le stockage du secret dans les fichiers du thème ou son rendu en HTML doit être évité. Seul le HMAC calculé doit atteindre la boutique en ligne.

Implémentation de référence (XML de mise en page + bloc + PHTML)

Cette implémentation crée :

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

Elle nécessite également un squelette de module minimal 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>

Après le déploiement des fichiers, activez le module et actualisez les fichiers générés ainsi que les caches.

Activez le module (exemple)

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

Ajoutez le XML de mise en page sur le tableau de bord client

Ajoutez une mise à jour de mise en page 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 entre les sessions.

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

Le bloc lit l’identifiant 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’identifiant client Magento comme magento.customer_Id. Si un identifiant CRM est stocké sur l’entité client, il peut être utilisé à la place.

Rendez le bouton cinto dans un modèle PHTML

Le modèle injecte l’identifiant de tenant, l’identifiant 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 repli pour ordinateur et détection de plateforme) est disponible dans Sur votre site web.

Notes sur le nom de l’identifiant externe

Les navigateurs convertissent les attributs HTML en minuscules. Le SDK cinto inclut une règle d’échappement pour préserver les majuscules en les préfixant avec _.

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

Facultatif : liste d’autorisation CSP Adobe Commerce

Certaines configurations Adobe Commerce imposent une Content Security Policy qui peut bloquer par défaut les scripts tiers. Si le script SDK est bloqué, ajoutez à la liste d’autorisation 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, ajouter l’hôte du SDK à la liste d’autorisation 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 appliqué). L’emplacement et le processus de la liste d’autorisation doivent correspondre aux conventions du projet.

Valider le résultat

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

Dans Safari sur iOS, le CTA doit afficher Ajouter à Apple Wallet.
Dans Chrome sur Android, 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 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 qu’attend The Wallet Crew. 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 de 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 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éré, car il garde le calcul du HMAC hors des modèles et centralise le chargement des secrets (configuration de déploiement ou variables d’environnement).

Quel identifiant client doit être utilisé ?

L’identifiant client interne d’Adobe Commerce est souvent utilisé car il est stable et toujours disponible sur la page de compte. Un projet peut également utiliser un identifiant 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’identifiants inviolable 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é à la boutique en ligne.

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

Oui. Le même schéma de carte-cadeau Wallet Magento fonctionne lorsque la carte-cadeau est émise en tant que 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 basculant data-neostore-passType et la clé/valeur d’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 du secret ?

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. Les exemples courants incluent une page de liste de cartes-cadeaux, un tableau de bord de fidélité ou une page de click & collect lorsqu’une Carte de retrait est utilisée comme jeton de scan en magasin.

Mis à jour il y a 2 mois