# Prestashop Cette intégration explique comment ajouter un **bouton unique « Ajouter à Wallet »** à la **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 Wallet mobile, en utilisant un identifiant disponible dans la session client de PrestaShop.
Add To Wallet integration with prestashop
La personnalisation de la vitrine PrestaShop se fait généralement via **modules** et **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 lors des mises à jour du thème.
Exemples concrets * Un programme de fidélité affiche « Ajouter à Wallet » sur le **Mon compte** tableau de bord pour les clients connectés. * Un programme de carte cadeau affiche un bouton par **carte cadeau** active dans la zone de compte. * Un flux click & collect affiche un CTA de pass de retrait sur une page de retrait authentifiée, en utilisant une référence de retrait comme identifiant.
{% hint style="info" %} Pour l'utilisation générique du SDK cinto (mode id de pass, détection de plateforme, personnalisation du QR sur desktop), voir [Sur votre site web](https://app.gitbook.com/s/WLc8AHXW4tdrAXUBfrYF/enroll/on-your-website). {% endhint %} ## Comment ça marche Le SDK cinto de The Wallet Crew affiche le bon CTA selon l'appareil. Sur iOS, le bouton télécharge un pass Apple Wallet. Sur Android, il ouvre Google Wallet. Sur desktop, le SDK redirige vers une page de pass hébergée qui peut être scannée ou ouverte sur mobile. Dans cette configuration PrestaShop, le pass est récupéré en utilisant un **type de pass** (exemple : `utilisateur`) et un **identifiant externe** dérivé de la session client connecté. L'identifiant est signé avec un **HMAC** calculé côté serveur. Cela rend l'échange d'identifiants à l'épreuve des falsifications et évite d'exposer des secrets dans la vitrine. {% hint style="warning" %} Le HMAC doit être calculé côté serveur. Il ne doit pas être généré dans le navigateur. {% endhint %} ## Prérequis * Un modèle de pass et l'émission de pass déjà configurés dans The Wallet Crew. * L'identifiant du tenant The Wallet Crew disponible (utilisé par l'URL du script 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'identifiant client PrestaShop. Un projet peut aussi utiliser un identifiant 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 en utilisant des 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 les autres plateformes e-commerce. 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 pass, l'identifiant et le HMAC. 4. Charger le script SDK cinto une seule fois par page. ### Où placer le bouton Les emplacements courants sont : * Le **Mon compte** le tableau de bord, à côté du numéro de fidélité ou d'adhésion. * Une **page Wallet / Fidélité** dédiée dans la zone de 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. Beaucoup de 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 {% stepper %} {% step %} #### Choisir le contrat d'identifiant externe The Wallet Crew récupère ou crée un pass à partir de : * `passType` (exemple : `utilisateur`) * `externalIdentifier.key` (exemple : `prestashop.customer_id`) * `externalIdentifier.value` (exemple : l'identifiant 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. {% hint style="info" %} Si le tenant The Wallet Crew utilise déjà une clé en casse mixte, la changer peut affecter les installations existantes. Traitez ceci comme un sujet de migration. {% endhint %} {% endstep %} {% step %} #### Stocker la configuration du tenant et le secret côté serveur L'identifiant du tenant peut être utilisé côté client. Le secret du HMAC doit rester côté serveur. Les approches courantes dans les déploiements PrestaShop sont : * 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 de thème ou rendu dans le HTML. Seul le HMAC calculé doit atteindre la vitrine. {% endstep %} {% step %} #### Créer un petit module qui affiche le bouton Le module typiquement : * S'enregistre sur un hook lié au compte, ou fournit un petit contrôleur pour une page de compte dédiée. * Lit l'identifiant client connecté depuis le contexte de session. * Calcule le HMAC en utilisant le secret côté serveur. * Assigne l'identifiant du tenant, le type de pass, 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 différents clients. {% endstep %} {% step %} #### Charger le SDK cinto une 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é par pass. Si la vitrine utilise des en-têtes de sécurité qui restreignent les scripts tiers, il est nécessaire de mettre l'hôte du SDK sur la liste autorisée. {% endstep %} {% endstepper %} ## Valider le résultat La validation couvre généralement le rendu sur la plateforme et l'installation du pass. 1. Sur iOS Safari, le CTA devrait afficher **Ajouter à Apple Wallet**. 2. Sur Android Chrome, le CTA devrait afficher **Ajouter à Google Wallet**. 3. Sur desktop, le CTA devrait rediriger vers une page de pass hébergée. 4. Après l'installation, le pass devrait être visible dans Apple Wallet ou Google Wallet. ## Dépannage ### Le bouton ne s'affiche pas Les causes les plus courantes sont le blocage du chargement du SDK (CSP ou restrictions de script) ou l'absence de balisage. Le HTML final doit contenir : * un script chargeur du SDK cinto * un élément conteneur configuré comme un bouton « Ajouter à Wallet » ### Cliquer sur le bouton génère une erreur Cela signifie généralement que l'identifiant externe ou le HMAC ne correspond pas à ce que The Wallet Crew attend. Confirmez : * Le nom de la clé d'identifiant externe correspond à celle configurée 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 sessions. Confirmez que : * les pages de compte ne sont pas mises en cache au niveau de la page * tout proxy inverse 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éré. Il permet d'extraire le calcul du HMAC des templates de thème et de centraliser le chargement des secrets.
Quel identifiant convient le mieux pour les passes de fidélité ? L'identifiant client PrestaShop est couramment utilisé car il est stable et disponible dans la session connectée. Un projet peut aussi utiliser un identifiant CRM s'il est persistant sur le client et reste stable dans le temps.
Où le secret du HMAC doit-il être stocké ? Le secret doit rester côté serveur. Les variables d'environnement ou un magasin de configuration protégé par le module sont des approches courantes. Il ne doit jamais être exposé dans les templates ou le code navigateur.
La même approche peut-elle être utilisée pour les cartes cadeaux ? Oui. Le même modèle fonctionne tant qu'un identifiant stable de carte cadeau existe et peut être signé côté serveur. Beaucoup de projets affichent un bouton par carte cadeau dans la zone de compte, avec un type de pass dédié pour les cartes cadeaux.
Le bouton peut-il être affiché en dehors de Mon compte ? Oui. Toute page authentifiée qui a 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 click & collect lorsqu'un pass de retrait est utilisé comme jeton de scan en magasin.