Salesforce Commerce Cloud (SFCC)

Ajoutez les boutons « Ajouter à Wallet » Apple Wallet et Google Wallet à une boutique Salesforce Commerce Cloud à l’aide d’une cartridge, de la signature HMAC côté serveur et du SDK cinto de The Wallet Crew.

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

Un identifiant stable disponible dans la session client est signé côté serveur, puis transmis au SDK cinto de The Wallet Crew comme identifiant externe. Cela rend l’échange d’identifiants inviolable et évite d’exposer des secrets dans le code de la vitrine.

Exemples réels

• Un programme de fidélité affiche « Add to Wallet » dans Mon compte pour les clients connectés.
• Un programme de cartes-cadeaux affiche un bouton par active carte-cadeau active dans le Wallet du compte.
• Un flux de click & collect affiche un CTA de carte de retrait sur une page de retrait dédiée, en utilisant une référence de retrait comme identifiant.

Pour l’utilisation générique du SDK cinto (mode d’id de carte, détection de plateforme, personnalisation du QR code desktop), voir Sur votre site Web.

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, des scripts, des modèles et des métadonnées de configuration, puis être intégré à 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é comme int_TheWalletCrew. Le cartridge est ensuite référencé par :

• l’application de vitrine (SFRA ou SiteGenesis)
• configuration de Business Manager (préférences de site et, éventuellement, objets personnalisés)

Cartridge

Un cartridge est l’unité de déploiement dans SFCC. L’ordre des cartridges compte car SFCC résout les modèles et les scripts en parcourant le chemin des cartridges de gauche à droite.

SFRA vs SiteGenesis

Les deux architectures peuvent prendre en charge l’intégration :

• SFRA: contrôleurs et modèles ISML. Le bouton est généralement ajouté dans un modèle de compte ou dans un remote include.
• SiteGenesis: pipelines (hérités) et modèles ISML. Le bouton est généralement ajouté dans une page de compte rendue par pipeline.

Le modèle de sécurité reste identique. Le HMAC est calculé côté serveur et jamais en JavaScript du navigateur.

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 SFCC, la carte est récupérée à l’aide de :

• un type de carte (exemple : user)
• un identifiant SFCC stable envoyé en tant qu’ identifiant externe (exemple : sfcc.customerNo)
• un HMAC signature qui prouve 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 de locataire The Wallet Crew est disponible (utilisé par l’URL du script SDK).
• Un identifiant stable disponible sur les pages authentifiées, tel que :

  • SFCC CustomerNo (typique pour les cartes de fidélité)
  • (typique pour les cartes de retrait click & collect)
  • (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

Le schéma typique est le suivant :

1. Lire l’identifiant dans le code côté serveur de SFCC.
2. Calculer un HMAC avec le secret du locataire.
3. Rendre un conteneur cinto dans le modèle ISML avec identifiant + HMAC.
4. Charger le SDK cinto depuis sdk.neostore.cloud.

1

Ajouter 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 avant le cartridge de base de la vitrine afin que les substitutions se résolvent correctement.

Les libellés exacts des menus de Business Manager varient selon la version de SFCC. Le point clé est le chemin des cartridges au niveau du site (et non le global).

2

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

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

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

Préférences recommandées (identifiants, types, exemples)

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

• theWalletCrewTenantId (String) Exemple : molia
• theWalletCrewHmacSecret (Password) Exemple : I1M8emrrJSns4Hnuibbm45eWfLQMosPGKSp1JzKsCrXeWmhjE8lZhxC2tfSRX5IJ
• theWalletCrewDefaultPassType (String) Exemple : user
• theWalletCrewExternalIdentifierKey (String) Exemple : sfcc.customerNo
• theWalletCrewLanguage (String, facultatif) Exemple : fr En l’absence de valeur, cinto utilise la détection de la langue du navigateur.

Conserver le secret comme une Mot de passe préférence permet d’éviter une divulgation accidentelle dans les exports d’interface et les captures d’écran.

Le secret HMAC ne doit pas être stocké dans les modèles, les contenus ou toute configuration côté client.

3

Calculer le HMAC côté serveur

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

Choix d’implémentation courants :

• un script d’aide exposé par le cartridge, utilisé par les contrôleurs de compte
• un modèle décorateur qui enrichit le modèle de vue avec identifiant et identifierHmac

Le cache doit être géré avec précaution. Les pages spécifiques à un client ne doivent pas partager de HTML mis en cache entre clients lorsque l’identifiant est intégré au balisage.

4

Rendre le bouton « Add to Wallet » en ISML

Le SDK cinto s’appuie sur :

• un script chargeur du SDK faisant référence à l’identifiant du locataire
• un élément conteneur marqué comme bouton « Add to Wallet »
• un passType
• une paire clé/valeur d’identifiant externe plus le HMAC côté serveur

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 click & collect).

Conventions des identifiants externes (casse + échappement)

Le SDK cinto peut récupérer une carte à partir d’un identifiant externe :

• passType (exemple : user)
• externalIdentifier.key (exemple : sfcc.customerNo)
• externalIdentifier.value (exemple : 00012345)
• externalIdentifier.hmac (HMAC-SHA256 de la valeur)

Convention de nommage recommandée pour les clés

L’option la plus stable consiste à éviter les majuscules/minuscules mixtes dans les clés d’identifiant.

Les clés sont généralement :

• préfixées par un espace de noms comme sfcc.
• en minuscules
• en utilisant _ comme séparateur lorsque nécessaire

Exemples :

• sfcc.customer_no
• sfcc.pickup_ref
• sfcc.gift_card_id

Si le locataire The Wallet Crew est déjà configuré avec une clé à casse mixte, la modifier peut avoir un impact sur les installations existantes. Un changement de nommage de clé doit être considéré comme un sujet de migration.

Si une clé à casse mixte doit être utilisée dans des attributs HTML

Les navigateurs traitent les noms d’attributs HTML comme étant en minuscules. cinto prend en charge une règle d’échappement pour les caractères majuscules dans data-neostore-externalIdentifiers-... attributs :

• Préfixez un caractère majuscule avec _ dans le nom de l’attribut.
• y2.customer_Id est interprété comme y2.customerId.

Appliqué aux exemples SFCC :

• Clé d’identifiant dans The Wallet Crew : sfcc.customerNo
• Clé d’identifiant dans les attributs HTML : sfcc.customer_No

Cela n’affecte que le nom de l’attribut, pas la valeur signée.

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 de site pour stocker la configuration du locataire
• un un helper HMAC côté serveur
• un 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.

Arborescence des fichiers du cartridge

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

1) Helper HMAC (cartridge/scripts/TheWalletCrew/hmac.js)

cartridge/scripts/TheWalletCrew/hmac.js

'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é en hexadécimal.
 * La sortie est mise en minuscules pour correspondre aux exemples cinto.
 */
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
};

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

Ce contrôleur rend un widget qu’il est sûr d’inclure comme inclusion distante.

cartridge/controllers/TheWalletCrew.js

'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 le cache pour éviter de servir l’identifiant d’un client à un autre.
    // La stratégie de cache-control diffère selon les bases 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 du 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);

    // Recommandé dans les modèles côté serveur : utilisez la forme d’attribut JSON.
    // Cela évite les pièges de casse des attributs HTML.
    var externalIdentifiers = {};
    externalIdentifiers[externalKey] = { value: identifierValue, hmac: identifierHmac };

    res.render('TheWalletCrew/addToWalletButton', {
        enabled: true,
        tenantId: tenantId,
        passType: passType,
        language: language,
        externalIdentifiersJson: JSON.stringify(externalIdentifiers)
    });

    return next();
});

module.exports = server.exports();

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

cartridge/templates/default/TheWalletCrew/addToWalletButton.isml

<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="<isprint value="${pdict.externalIdentifiersJson}" encoding="off" />">
    </div>
</isif>

Le chargeur de script doit être inclus une seule fois par page. Lorsque plusieurs boutons sont rendus sur la même page, déplacez le chargeur dans un fragment de pied de page partagé et conservez uniquement le <div data-neostore-addToWalletButton ...> le balisage dans le modèle du widget.

4) Inclure le widget dans un modèle de compte

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

Exemple d’inclusion (ISML)

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

Politique de sécurité du contenu (CSP)

Certaines vitrines SFCC appliquent une politique de sécurité du contenu qui bloque par défaut les scripts tiers. Si le script du SDK est bloqué, l’ajout à la liste d’autorisation de https://sdk.neostore.cloud pour script-src est requis.

Dans les projets SFRA, la CSP est souvent gérée via des middlewares et des en-têtes de réponse. Le changement doit suivre la stratégie CSP existante du projet (mode rapport uniquement vs application forcée).

Valider le résultat

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

1. Sur Safari iOS, le CTA doit afficher Ajouter à Apple Wallet.
2. Sur Chrome 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 l’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. La page rendue doit contenir le chargeur du SDK et l’élément conteneur cinto.

Cliquer sur le bouton provoque une erreur

Cela signifie généralement que l’identifiant externe ou le HMAC ne correspond pas à ce que The Wallet Crew attend. Vérifiez :

• que le nom de la clé d’identifiant externe correspond à celui configuré pour SFCC (exemple : sfcc.customerNo)
• que la valeur de l’identifiant correspond exactement à celle signée côté serveur (sans suppression d’espaces, mise en forme ni changement de type)
• que le HMAC a été calculé avec le bon secret du locataire

Le bouton s’affiche pour le mauvais client

Cela indique généralement un cache HTML partagé entre sessions. Assurez-vous que :

• les pages spécifiques à un client ne sont pas mises en cache au niveau de la page
• les inclusions distantes utilisées pour les widgets de compte ne sont pas mises en cache d’un client à l’autre
• toute couche CDN respecte les cookies de session pour les pages authentifiées

FAQ

Qu’est-ce qu’un cartridge dans SFCC ?

Un cartridge est l’unité déployable qui contient le code de vitrine et les métadonnées. Le chemin des cartridges du site définit quels cartridges sont actifs et dans quel ordre ils sont résolus.

Quel identifiant convient le mieux pour les cartes de fidélité ?

Le numéro client SFCC (CustomerNo) est couramment utilisé car il est stable et disponible sur les pages authentifiées. Un identifiant CRM peut également être utilisé s’il est conservé sur le profil et reste stable dans le temps.

Où le secret du locataire doit-il être stocké dans SFCC ?

Les préférences de site personnalisées sont généralement utilisées car elles restent côté serveur et peuvent être gérées par site. Le secret ne doit jamais être exposé dans les modèles, les ressources de contenu ou le JavaScript du navigateur.

La même approche peut-elle être utilisée pour les cartes-cadeaux et le click & collect ?

Oui. Le même schéma fonctionne tant qu’un identifiant stable existe pour l’objet et que le bouton peut être rendu sur une page ayant accès à cet identifiant côté serveur.

L’intégration nécessite-t-elle SFRA ?

Non. SFRA et SiteGenesis peuvent tous deux prendre en charge le même schéma HMAC côté serveur + rendu de modèle. Seuls les points d’entrée d’implémentation diffèrent (contrôleurs vs pipelines).