> 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/salesforce-commerce-cloud.md).

# Salesforce Commerce Cloud (SFCC)

Ajoutez des boutons Apple Wallet et Google Wallet à une vitrine Salesforce Commerce Cloud à l'aide d'une cartridge, d'une signature HMAC côté serveur et du SDK The Wallet Crew.

Cette intégration explique comment ajouter un **bouton unique « Ajouter à Wallet »** à une vitrine Salesforce Commerce Cloud. Les emplacements courants sont la **section Mon compte** (carte de fidélité ou carte d'adhésion) et les pages authentifiées où un identifiant stable est disponible (par exemple une liste de cartes cadeaux). Les pages de retrait et collecte peuvent aussi convenir lorsqu'une carte de retrait est utilisée comme jeton de scan en magasin.

## Concepts SFCC utilisés dans cette intégration

Le code de la vitrine Salesforce Commerce Cloud est empaqueté et déployé sous forme de **cartridges**. Un cartridge peut ajouter des contrôleurs, scripts, templates et métadonnées de configuration, puis être branché à un site en l'ajoutant au **chemin des cartridges**.

Ce guide suppose qu'un cartridge dédié est créé pour l'intégration The Wallet Crew, généralement nommé par exemple `int_TheWalletCrew`. Le cartridge est ensuite référencé par :

* l'application de vitrine (SFRA ou SiteGenesis)
* la configuration de Business Manager (préférences du site et, éventuellement, objets personnalisés)

L'ordre des cartridges est important, car SFCC résout les templates et les scripts en parcourant le chemin des cartridges de gauche à droite.

L'exemple ci-dessous cible SFRA : contrôleurs et templates ISML, avec le bouton ajouté dans un template de compte ou via une inclusion distante. Aucun exemple SiteGenesis n'est fourni : une vitrine SiteGenesis adapte les points d'entrée (pipelines) et conserve le même modèle de sécurité, avec le HMAC calculé côté serveur.

## 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 le numéro client SFCC comme clé d'identifiant externe `sfcc.customerNo`.

## 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 stable disponible sur les pages authentifiées, par exemple :
  * SFCC `CustomerNo` (typique pour les cartes de fidélité)
  * (référence de retrait typique pour les cartes de retrait et collecte)
  * (identifiant de carte cadeau, lorsque les cartes cadeaux sont stockées dans SFCC ou dans un système connecté)
* Le nom de la clé d'identifiant externe convenu lors de l'intégration (exemple : `sfcc.customerNo`).

## Implémentez l'intégration sous forme de cartridge

{% stepper %}
{% step %}

#### Ajoutez le cartridge au chemin des cartridges

Après avoir déployé le cartridge d'intégration sur l'instance, ajoutez-le au chemin des cartridges du site dans Business Manager. Le cartridge doit être placé **avant** le cartridge de base de la vitrine afin que les remplacements se résolvent correctement.

Dans Business Manager, ouvrez **Administration → Sites → Gérer les sites**, sélectionnez le site, puis ouvrez l'onglet **Paramètres** . Ajoutez le cartridge au champ **Cartridges** (une liste séparée par des deux-points : les cartridges situés à gauche sont prioritaires) et cliquez sur **Appliquer**.

{% hint style="info" %}
Le point clé est le **chemin des cartridges au niveau du site** (et non celui de Business Manager).
{% endhint %}
{% endstep %}

{% step %}

#### Stockez la configuration du tenant sous forme de préférences du site

Les valeurs et secrets du tenant doivent rester côté serveur. Dans SFCC, cela se fait généralement avec **des préférences de site personnalisées**.

Au minimum, ces valeurs sont généralement requises.

<details>

<summary><strong>Préférences recommandées (IDs, types, exemples)</strong></summary>

Ces valeurs sont généralement créées sous forme de **préférences personnalisées au niveau du site** (et non au niveau de l'organisation).

* `theWalletCrewTenantId` (Chaîne)\
  Exemple : `<tenantId>`
* `theWalletCrewHmacSecret` (Mot de passe)\
  Exemple : `<your-secret>`
* `theWalletCrewDefaultPassType` (Chaîne)\
  Exemple : `user`
* `theWalletCrewExternalIdentifierKey` (Chaîne)\
  Exemple : `sfcc.customerNo`
* `theWalletCrewLanguage` (Chaîne, facultatif)\
  Exemple : `fr`\
  En l'absence de valeur, le SDK utilise la détection de la langue du navigateur.

</details>
{% endstep %}

{% step %}

#### Calculez le HMAC côté serveur

Les scripts côté serveur SFCC peuvent calculer un HMAC SHA-256 à l'aide du secret du tenant et de la valeur exacte de l'identifiant.

Choix d'implémentation courants :

* un script utilitaire exposé par le cartridge, utilisé par les contrôleurs de compte
* un pattern décorateur qui enrichit le modèle de vue avec `identifier` et `identifierHmac`
  {% endstep %}

{% step %}

#### Rendre le bouton « Ajouter à Wallet » en ISML

Le cartridge d'intégration fournit généralement un fragment ISML pouvant être inclus là où c'est nécessaire (tableau de bord du compte, liste de cartes cadeaux, page de retrait en magasin).
{% endstep %}
{% endstepper %}

## Conventions d'identifiant externe

### Convention de nommage des clés recommandée

Les clés sont généralement :

* préfixées avec un espace de noms comme `sfcc.`
* écrites en camelCase, sans `_`

Exemples :

* `sfcc.customerNo`
* `sfcc.pickupRef`
* `sfcc.giftCardId`

Dans l'attribut, la clé `sfcc.customerNo` est écrite `sfcc.customer_No`: voir [Fonctionnement du bouton Ajouter à Wallet](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works). Le préfixe `neostore` est l'ancien nom de la plateforme et est conservé dans les identifiants techniques.

{% hint style="info" %}
Si le tenant The Wallet Crew est déjà configuré avec une clé, sa modification peut impacter les installations existantes. Un changement de nom de clé doit être considéré comme un sujet de migration.
{% endhint %}

## Implémentation de référence SFRA à copier/coller (contrôleur + fragment ISML)

Cette implémentation de référence utilise :

* **les préférences du site** pour stocker la configuration du tenant
* un **utilitaire HMAC côté serveur**
* un **contrôleur d'inclusion distante** qui rend un fragment ISML

Elle est conçue pour être collée dans un cartridge dédié (exemple : `int_TheWalletCrew`) et appelée depuis une page de compte.

### Structure des fichiers du cartridge

* `cartridge/scripts/TheWalletCrew/hmac.js`
* `cartridge/controllers/TheWalletCrew.js`
* `cartridge/templates/default/TheWalletCrew/addToWalletButton.isml`

### 1) Utilitaire HMAC (`cartridge/scripts/TheWalletCrew/hmac.js`)

The Wallet Crew compare le HMAC hexadécimal sans tenir compte de la casse, donc les minuscules et les majuscules sont toutes deux acceptées.

{% code title="cartridge/scripts/TheWalletCrew/hmac.js" %}

```javascript
'use strict';

var Mac = require('dw/crypto/Mac');
var Encoding = require('dw/crypto/Encoding');

/**
 * HMAC-SHA256 sur la chaîne brute de l'identifiant (UTF-8), encodée en hexadécimal.
 * La sortie est mise en minuscules pour correspondre aux exemples du SDK.
 */
function hmacSha256Hex(secret, identifierValue) {
    var mac = new Mac(Mac.HMAC_SHA_256);
    var bytes = mac.digest(identifierValue, secret);
    return Encoding.toHex(bytes).toLowerCase();
}

module.exports = {
    hmacSha256Hex: hmacSha256Hex
};
```

{% endcode %}

### 2) Contrôleur (`cartridge/controllers/TheWalletCrew.js`)

Ce contrôleur rend un widget sûr à inclure via une inclusion distante.

{% code title="cartridge/controllers/TheWalletCrew\.js" %}

```javascript
'use strict';

var server = require('server');
var Site = require('dw/system/Site');

var theWalletCrewHmac = require('*/cartridge/scripts/TheWalletCrew/hmac');

server.get('Button', function (req, res, next) {
    // Désactivez la mise en cache pour éviter de servir l'identifiant d'un client à un autre.
    // La stratégie de cache-control varie selon les versions SFRA, donc gardez-la explicite.
    res.setHttpHeader('Cache-Control', 'no-store, no-cache, must-revalidate, max-age=0');
    res.setHttpHeader('Pragma', 'no-cache');

    var site = Site.getCurrent();
    var tenantId = site.getCustomPreferenceValue('theWalletCrewTenantId');
    var secret = site.getCustomPreferenceValue('theWalletCrewHmacSecret');
    var passType = site.getCustomPreferenceValue('theWalletCrewDefaultPassType') || 'user';
    var externalKey = site.getCustomPreferenceValue('theWalletCrewExternalIdentifierKey') || 'sfcc.customerNo';
    var language = site.getCustomPreferenceValue('theWalletCrewLanguage');

    // Exemple d'identifiant : numéro client connecté.
    var identifierValue = (customer && customer.profile) ? customer.profile.customerNo : null;

    if (!tenantId || !secret || !identifierValue) {
        res.render('TheWalletCrew/addToWalletButton', { enabled: false });
        return next();
    }

    var identifierHmac = theWalletCrewHmac.hmacSha256Hex(secret, identifierValue);

    // Les noms d'attribut sont mis en minuscules par le navigateur : le SDK lit "_x" comme "X".
    // Échappez chaque lettre majuscule de la clé (sfcc.customerNo -> sfcc.customer_No).
    var attributeKey = externalKey.replace(/([A-Z])/g, '_$1');

    res.render('TheWalletCrew/addToWalletButton', {
        enabled: true,
        tenantId: tenantId,
        passType: passType,
        language: language,
        attributeKey: attributeKey,
        identifierValue: identifierValue,
        identifierHmac: identifierHmac
    });

    return next();
});

module.exports = server.exports();
```

{% endcode %}

### 3) Fragment ISML (`cartridge/templates/default/TheWalletCrew/addToWalletButton.isml`)

{% code title="cartridge/templates/default/TheWalletCrew/addToWalletButton.isml" %}

```html
<isif condition="${pdict.enabled}">
    <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, "${pdict.tenantId}", <isprint value="${pdict.language ? ('{ \"language\": \"' + pdict.language + '\" }') : '{ }'}" encoding="off" />);
    </script>

    <div
        data-neostore-addToWalletButton
        data-neostore-passType="${pdict.passType}"
        data-neostore-externalIdentifiers-${pdict.attributeKey}-value="${pdict.identifierValue}"
        data-neostore-externalIdentifiers-${pdict.attributeKey}-hmac="${pdict.identifierHmac}">
    </div>
</isif>
```

{% endcode %}

### 4) Incluez le widget dans un template de compte

Dans SFRA, les inclusions distantes sont couramment utilisées pour éviter d'encombrer le contrôleur principal et pour garder la mise en cache explicite.

{% code title="Exemple d'inclusion (ISML)" %}

```html
<isinclude url="${URLUtils.url('TheWalletCrew-Button')}" />
```

{% endcode %}

## Politique de sécurité du contenu (CSP)

Dans les projets SFRA, la CSP est souvent gérée via des middleware et des en-têtes de réponse. Le changement doit suivre la stratégie CSP existante du projet (report-only ou enforced). Voir la [règle CSP](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#how-the-add-to-wallet-button-works).

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

Voir les [vérifications de dépannage](https://docs.thewalletcrew.io/connectors/fr/e-commerce.md#troubleshooting) de la vue d'ensemble du commerce électronique. Le nom de la clé d'identifiant externe doit correspondre à celui configuré pour SFCC (exemple : `sfcc.customerNo`).


---

# 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/salesforce-commerce-cloud.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.
