Prestashop

Ajoutez des boutons « Ajouter à Wallet » Apple Wallet et Google Wallet à une boutique PrestaShop à l’aide d’un module, d’une 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 » vers le Mon compte zone dans PrestaShop. Cette intégration PrestaShop Apple Wallet / Google Wallet aide les clients à enregistrer un carte de fidélité ou d’adhésion (et éventuellement une carte-cadeau Wallet) directement dans leur Wallet mobile, en utilisant un identifiant disponible dans la session client PrestaShop.

Résultat cible : un bouton « Ajouter au Wallet » affiché pour le client connecté dans Mon compte.

La personnalisation de la boutique PrestaShop se fait généralement via des modules et des surcharges de thème. Ce guide se concentre sur une approche basée sur un module afin de conserver les secrets côté serveur et de maintenir l’intégration facile à entretenir lors des mises à jour du thème.

Exemples réels

• Un programme de fidélité affiche « Ajouter à Wallet » sur le Mon compte tableau de bord pour les clients connectés.
• Un programme de cartes-cadeaux affiche un bouton par carte-cadeau carte cadeau dans l’espace de compte.
• Un parcours pick & collect affiche un CTA de Carte de retrait sur une page de retrait authentifiée, en utilisant une référence de retrait comme identifiant.

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.

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 PrestaShop, la Carte est récupérée à l’aide d’un type de Carte (exemple : utilisateur) et un identifiant externe dérivé de la session du client connecté. L’identifiant est signé avec un HMAC calculé côté serveur. Cela rend l’échange d’identifiants inviolable et évite d’exposer les secrets dans la boutique.

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 du tenant The Wallet Crew disponible (utilisé par l’URL du script du SDK).
• Un identifiant stable disponible sur les pages authentifiées.
• Un nom de clé d’identifiant externe convenu lors de l’intégration.

L’identifiant stable est souvent l’ID client PrestaShop. Un projet peut aussi utiliser un ID CRM s’il est stocké sur l’entité client et reste stable dans le temps.

Approche d’implémentation (module + hook ou surcharge de thème)

Les modules PrestaShop peuvent injecter des blocs dans les pages à l’aide de hooks. Les thèmes peuvent également être surchargés lorsqu’un placement plus spécifique est requis.

Le schéma d’intégration recommandé reste cohérent avec celui des autres plateformes de commerce électronique.

1. Lire un identifiant stable côté serveur.
2. Calculer un HMAC avec le secret du tenant.
3. Rendre un élément conteneur cinto avec le type de Carte, l’identifiant et le HMAC.
4. Charger le script du SDK cinto une seule fois par page.

Où placer le bouton

Les emplacements courants sont :

• Le Mon compte tableau de bord, à côté du numéro de fidélité ou d’adhésion.
• Une page dédiée Wallet / Fidélité dans l’espace de compte.
• Une page de liste de cartes cadeau, avec un bouton par carte cadeau.

La disponibilité des hooks dépend du thème et de la version de PrestaShop. De nombreux projets utilisent un hook de module pour le tableau de bord du compte. Certains projets utilisent une surcharge de thème pour placer le bouton dans une section spécifique.

Étapes de configuration

1

Choisir le contrat d’identifiant externe

The Wallet Crew récupère ou crée une Carte à partir de :

• passType (exemple : utilisateur)
• externalIdentifier.key (exemple : prestashop.customer_id)
• externalIdentifier.value (par exemple : l’ID du client connecté)
• externalIdentifier.hmac (HMAC-SHA256 de la valeur)

Les clés d’identifiant doivent rester stables dans le temps. Les clés en minuscules réduisent les problèmes de casse des attributs HTML et facilitent la maintenance à long terme.

Si le tenant The Wallet Crew utilise déjà une clé avec casse mixte, la modifier peut affecter les installations existantes. Considérez cela comme un sujet de migration.

2

Stocker la configuration du tenant et le secret côté serveur

L’ID du tenant peut être utilisé côté client. Le secret HMAC doit rester côté serveur.

Les approches courantes dans les déploiements PrestaShop sont :

• des variables d’environnement injectées par la plateforme d’hébergement.
• Un magasin de configuration côté serveur géré par le module, avec un contrôle d’accès strict dans le back-office.

Le secret ne doit pas être stocké dans les fichiers du thème ni rendu en HTML. Seul le HMAC calculé doit parvenir à la boutique.

3

Construire un petit module qui affiche le bouton

Le module :

• S’enregistre sur un hook lié au compte, ou fournit un petit contrôleur pour une page de compte dédiée.
• Lit l’ID du client connecté à partir du contexte de session.
• Calcule le HMAC à l’aide du secret côté serveur.
• Affecte l’ID du tenant, le type de Carte, la valeur de l’identifiant et le HMAC aux variables du template.

La mise en cache doit être gérée explicitement. Les pages de compte ne doivent pas être mises en cache entre les clients.

4

Charger le SDK cinto une seule fois par page

Le chargeur du SDK cinto doit être inclus une seule fois par page. Lorsque plusieurs boutons existent sur la même page, le chargeur doit être placé dans un partial de pied de page ou d’en-tête partagé et le balisage du bouton doit être répété pour chaque Carte.

Si la boutique utilise des en-têtes de sécurité qui restreignent les scripts tiers, il faut autoriser le domaine d’hébergement du SDK.

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 les plus courantes sont un chargement du SDK bloqué (CSP ou restrictions de script) ou un balisage manquant. Le HTML final doit contenir :

• un script chargeur du SDK cinto
• un élément conteneur configuré comme bouton « Add to Wallet »

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 le tenant.
• La valeur de l’identifiant correspond exactement à ce qui est signé côté serveur.
• Le HMAC est calculé avec le bon secret du tenant.

Le bouton s’affiche pour le mauvais client

Cela indique généralement une mise en cache entre les sessions. Vérifiez que :

• les pages de compte ne sont pas mises en cache au niveau de la page
• tout reverse proxy ou CDN respecte les cookies de session sur les routes authentifiées

FAQ

Cela nécessite-t-il un module PrestaShop personnalisé ?

Une surcharge de thème peut suffire lorsque les valeurs côté serveur sont déjà disponibles dans le contexte du template. Un module dédié est généralement préférable. Il maintient le calcul du HMAC hors des templates du thème et centralise le chargement du secret.

Quel identifiant fonctionne le mieux pour les Cartes de fidélité ?

L’ID client PrestaShop est couramment utilisé car il est stable et disponible dans la session connectée. Un projet peut aussi utiliser un ID CRM s’il est persisté sur le client et reste stable dans le temps.

Où faut-il stocker le secret HMAC ?

Le secret doit rester côté serveur. Les variables d’environnement ou un magasin de configuration protégé du module sont des approches courantes. Il ne doit jamais être exposé dans les templates ou le code du navigateur.

La même approche peut-elle être utilisée pour les cartes-cadeaux ?

Oui. Le même schéma fonctionne tant qu’un identifiant stable de carte cadeau existe et peut être signé côté serveur. De nombreux projets affichent un bouton par carte cadeau dans l’espace de compte, avec un type de Carte dédié aux cartes cadeau.

Le bouton peut-il être affiché en dehors de Mon compte ?

Oui. Toute page authentifiée ayant accès à l’identifiant stable côté serveur peut afficher le bouton. Les exemples courants sont un tableau de bord de fidélité, une page de liste de cartes cadeau ou une page pick & collect lorsqu’une Carte de retrait est utilisée comme jeton de scan en magasin.