Aller au contenu
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Ce guide ajoute un bouton « Add to Wallet » à la section Mon compte zone de Adobe Commerce (Magento 2), pour une carte de fidélité ou d’adhésion (ou une carte-cadeau Wallet), en utilisant un identifiant disponible dans la session client Adobe Commerce.

Adobe Commerce My Account page showing an “Add to Wallet” button.
Résultat cible : un bouton « Add to Wallet » rendu pour le client connecté dans Mon compte.

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

Fonctionnement

Le SDK, la règle HMAC, la mise en cache et la CSP sont expliqués dans Fonctionnement du bouton Ajouter à Wallet. Ce guide utilise l’identifiant client Magento comme clé d’identifiant externe magento.customerId.

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 du 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.customerId) est défini lors de l’intégration du projet.

Ajoutez le bouton à la page de compte client Adobe Commerce

Les pages de la boutique Adobe Commerce sont construites à partir de layout XML et modèles PHTML. Rendre le bouton depuis un bloc Magento conserve les secrets côté serveur et permet un échappement sûr pour les 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 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 puissent pas être modifiées depuis l’Admin Adobe Commerce.

Option B : stocker le secret sous forme de variable d’environnement

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

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é lors du déploiement.

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

Cette implémentation crée :

  • un Bloc classe qui lit l’ID du client connecté et calcule le HMAC

  • un template 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 aussi un squelette de module minimal afin qu’Adobe Commerce puisse charger les fichiers. Le préfixe neostore est l'ancien nom de la plateforme et est conservé dans les identifiants techniques.

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

1

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.

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

2

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).

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

3

Affichez le bouton dans un template PHTML

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

Les navigateurs mettent les noms d’attributs en minuscules, donc la clé magento.customerId est écrite magento.customer_Id dans l’attribut : le SDK lit un souligné suivi d’une lettre comme cette lettre en majuscule. Voir Fonctionnement du bouton Ajouter à Wallet.

fr est une valeur d’exemple. 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 (options, solution de repli sur ordinateur de bureau et détection de plateforme) est disponible dans Sur votre site web.

Facultatif : liste d’autorisation CSP d’Adobe Commerce

Si le script du SDK est bloqué par une Content Security Policy, consultez règle CSP.

La configuration CSP de Magento diffère selon les versions et les configurations. Si CSP est activée, 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.

Validez le résultat

Suivez les étapes de validation de la vue d'ensemble du commerce électronique.

Dépannage

Commencez par la vérifications de dépannage de la vue d’ensemble e-commerce. Dans l’attribut, la clé magento.customerId est écrite magento.customer_Id.

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 maintient le calcul du HMAC hors des templates et centralise le chargement des secrets (configuration de déploiement ou variables d’environnement).

Mis à jour