PrestaShop
Ajoutez des boutons Apple Wallet et Google Wallet « Ajouter à Wallet » à une boutique PrestaShop à l’aide d’un module, 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 » vers le Mon compte zone dans PrestaShop. Cette intégration PrestaShop 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 portefeuille mobile, en utilisant un identifiant disponible dans la session client PrestaShop.
La personnalisation de la vitrine 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 garder l'intégration maintenable lors des mises à jour du thème.
Exemples concrets
Un programme de fidélité affiche « Add to Wallet » sur le Mon compte tableau de bord des clients connectés.
Un programme de cartes-cadeaux affiche un bouton par active carte cadeau dans la zone du 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 id de Carte, détection de plateforme, personnalisation du QR code sur ordinateur), voir Sur votre site web.
Fonctionnement
Le SDK cinto de The Wallet Crew affiche le CTA approprié 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 sur la vitrine.
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'onboarding.
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 aussi être surchargés lorsqu'un emplacement plus spécifique est requis.
Le modèle d'intégration recommandé reste cohérent avec d'autres plateformes de commerce électronique.
Lire un identifiant stable côté serveur.
Calculer un HMAC avec le secret du tenant.
Rendre un élément conteneur cinto avec le type de Carte, l'identifiant et le HMAC.
Charger le script du SDK cinto une seule fois par page.
Où placer le bouton
Les emplacements courants sont :
La 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 la zone du compte.
Une page de liste de cartes cadeaux, 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
Choisir le contrat d'identifiant externe
The Wallet Crew récupère ou crée une Carte à partir de :
CarteType(exemple :utilisateur)externalIdentifier.key(exemple :prestashop.customer_id)externalIdentifier.value(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 locataire The Wallet Crew utilise déjà une clé avec des majuscules et minuscules, la modifier peut affecter les installations existantes. Traitez cela comme un sujet de migration.
Stocker la configuration du locataire et le secret côté serveur
L'ID du locataire 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 vitrine.
Construire un petit module qui rend 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é depuis le contexte de session.
Calcule le HMAC à l'aide du secret côté serveur.
Attribue l'ID du locataire, le type de Carte, la valeur de l'identifiant et le HMAC aux variables du modèle.
La mise en cache doit être gérée explicitement. Les pages de compte ne doivent pas être mises en cache entre les clients.
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 composant partagé de pied de page ou d'en-tête et le balisage du bouton doit être répété par Carte.
Si la vitrine utilise des en-têtes de sécurité qui restreignent les scripts tiers, il faut autoriser le domaine hôte du SDK.
Validez le résultat
La validation couvre généralement le rendu de la plateforme et l’installation de la Carte.
Sur iOS Safari, le CTA doit afficher Ajouter à Apple Wallet.
Sur Android Chrome, le CTA doit afficher Ajouter à Google Wallet.
Sur ordinateur, le CTA doit rediriger vers une page de Carte hébergée.
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 que The Wallet Crew attend. Vérifiez :
Le nom de la clé d'identifiant externe correspond à celui configuré pour le locataire.
La valeur de l'identifiant correspond exactement à ce qui est signé côté serveur.
Le HMAC est calculé avec le bon secret du locataire.
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 modèle. Un module dédié est généralement préférable. Il garde le calcul du HMAC hors des modèles de 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é parce qu'il est stable et disponible dans la session connectée. Un projet peut aussi utiliser un ID CRM s'il est conservé 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 de module protégé sont des approches courantes. Il ne doit jamais être exposé dans les modèles 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 la zone du compte, avec un type de Carte dédié aux cartes cadeaux.
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. Des exemples courants sont un tableau de bord de fidélité, une page de liste de cartes cadeaux, ou une page pick & collect lorsqu'une Carte de retrait est utilisée comme jeton de scan en magasin.
Mis à jour