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

<figure><img src="https://1459665471-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-54466c25c788732b1d188eee7d08928f86e5a51d%2Fadobe-commerce-my-account-add-to-wallet.png?alt=media" alt="Adobe Commerce My Account page showing an “Add to Wallet” button."><figcaption><p>Résultat cible : un bouton « Add to Wallet » rendu pour le client connecté dans Mon compte.</p></figcaption></figure>

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](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works). 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.

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

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

{% endcode %}

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

{% 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é lors du déploiement.
{% endhint %}

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

{% 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 %}

Une fois les fichiers déployés, 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 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.

{% 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 d’une session à l’autre.
{% endstep %}

{% step %}

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

{% 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'));
    }

    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'));
        }
        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’ID client Magento comme `magento.customerId`. Si un ID CRM est stocké sur l’entité client, il peut être utilisé à la place.
{% endhint %}
{% endstep %}

{% step %}

#### Affichez le bouton dans un template PHTML

Le template injecte l’ID du tenant, l’ID du 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 %}

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](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works).

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

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

### Facultatif : liste d’autorisation CSP d’Adobe Commerce

Si le script du SDK est bloqué par une Content Security Policy, consultez [règle CSP](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works).

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

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.

{% 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 (report-only ou appliquée). L’emplacement de la liste d’autorisation et le processus doivent correspondre aux conventions du projet.
{% endhint %}

## Validez le résultat

Suivez les [étapes de validation](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works) de la vue d'ensemble du commerce électronique.

## Dépannage

Commencez par la [vérifications de dépannage](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#troubleshooting) 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

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

</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
