> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/fr/e-commerce/adobe-commerce-magento.md).

# Adobe Commerce (Magento)

Intégration Magento (Adobe Commerce) pour ajouter des boutons « Add to 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.

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-2d4e3baec7d687196701581f3ce6edcee07a9339%2Fimage%20(1)%20(1)%20(1).png?alt=media" alt="Adobe Commerce My Account page showing an “Add to Wallet” button."><figcaption><p>Résultat cible : un bouton « Ajouter au Wallet » affiché pour le client connecté dans Mon compte.</p></figcaption></figure>

<details>

<summary><strong>Exemples réels</strong></summary>

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

</details>

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

{% hint style="info" %}
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](/guides-enrolment/fr/inscription/on-your-website.md).
{% endhint %}

### 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

{% hint style="warning" %}
Le HMAC doit être calculé côté serveur. Il ne doit pas être généré dans le navigateur.
{% endhint %}

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

{% code title="app/etc/env.php (exemple)" %}

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

{% endcode %}

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

{% code title="Variables d’environnement (exemple)" %}

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

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

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

{% code title="app/code/Vendor/WalletCrewCinto/registration.php" %}

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

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

{% endcode %}

{% code title="app/code/Vendor/WalletCrewCinto/etc/module.xml" %}

```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>
```

{% endcode %}

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

{% code title="Activez le module (exemple)" %}

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

{% endcode %}

{% stepper %}
{% step %}

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

{% code title="app/code/Vendor/WalletCrewCinto/view/frontend/layout/customer\_account\_index.xml" %}

```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>
```

{% endcode %}

`cacheable="false"` garantit que les identifiants spécifiques au client ne sont pas mis en cache entre les sessions.
{% endstep %}

{% step %}

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

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

{% code title="app/code/Vendor/WalletCrewCinto/Block/AddToWallet.php" %}

```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);
    }
}
```

{% endcode %}

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

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

{% code title="app/code/Vendor/WalletCrewCinto/view/frontend/templates/add-to-wallet.phtml" %}

```php
<?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>
```

{% endcode %}

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

{% hint style="info" %}
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](/guides-enrolment/fr/inscription/on-your-website.md).
{% endhint %}
{% endstep %}
{% endstepper %}

#### 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`.

{% hint style="info" %}
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.
{% endhint %}

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.

{% code title="app/code/Vendor/WalletCrewCinto/etc/csp\_whitelist.xml (exemple)" %}

```xml
<?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>
```

{% endcode %}

{% hint style="warning" %}
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.
{% endhint %}

### Valider le résultat

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

1. Dans Safari sur iOS, le CTA doit afficher **Ajouter à Apple Wallet**.
2. Dans Chrome sur Android, le CTA doit afficher **Ajouter à Google Wallet**.
3. Sur ordinateur, le CTA doit rediriger vers une page de Carte hébergée.
4. 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

<details>

<summary><strong>Cela nécessite-t-il un module personnalisé ?</strong></summary>

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

</details>

<details>

<summary><strong>Quel identifiant client doit être utilisé ?</strong></summary>

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.

</details>

<details>

<summary><strong>D’où vient le secret HMAC ?</strong></summary>

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.

</details>

<details>

<summary><strong>La même approche peut-elle être utilisée pour les cartes-cadeaux ?</strong></summary>

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.

</details>

<details>

<summary><strong>Comment gérer la rotation du secret ?</strong></summary>

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.

</details>

<details>

<summary><strong>Le bouton peut-il être affiché ailleurs que sur la page de compte ?</strong></summary>

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.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thewalletcrew.io/connectors/fr/e-commerce/adobe-commerce-magento.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.