Page de présentation du programme
Le widget "Page de présentation du programme" d'Enkore met à disposition des consommateurs les éléments du programme de fidélité de la boutique (solde, historique, récompenses, parrainage).
Objectif du widget
La page de présentation du programme poursuit quatre objectifs :
- Présenter le fonctionnement du programme : comment gagner des points, à quoi ils donnent droit, quelles sont les règles.
- Renforcer l'univers du programme : bannière, textes, couleurs et CSS personnalisé permettent d'aligner la page sur l'identité de la marque.
- Informer le consommateur de l'état de son compte fidélité : solde de points et historique des mouvements encore valides.
- Lui permettre d'échanger ses points : conversion du solde en récompense (bon d'achat, réduction) et parrainage d'un ami.
Deux modes d'intégration sont possibles : l'intégration par script javascript, où Enkore fournit le rendu complet de la page, et l'intégration par API, où la boutique construit son propre affichage à partir des endpoints de l'API.
Intégration à l'aide du script
Le widget est un bundle JavaScript autonome, chargé par une balise <script>. Il cherche dans la page l'élément d'ancrage, s'y monte, et lit dans le HTML les informations que le back-end de la boutique a ajoutées.
Ce que le back-end doit exposer dans le HTML
| Élément | Rôle | Obligatoire |
|---|---|---|
<div id="enkore-loyalty-program"></div> | Point de montage du widget | Oui |
<div id="enkore-loyalty-hash" hidden>…</div> | HMAC-SHA512 du client, en innerText | Oui pour un client connecté |
<div id="enkore-loyalty-id" hidden>…</div> | Identifiant du client dans la plateforme e-commerce (externalId), en innerText | Oui pour un client connecté |
<div id="enkore-language" hidden data-enkore-language-iso="fr"></div> | Code ISO de la langue de la page | Non |
<div id="enkore-store-domain" data-enkore-domain="https://monstore.com"></div> | Domaine du store déclaré chez Enkore | Non |
Quelques précisions :
- Le hash et l'
externalIdvont de pair. Ils identifient le client auprès de l'API sans session ni cookie. Le hash est calculé côté serveur à partir de la référence du store et de sa clé API — voir la page Authentification par hash. La clé API ne doit jamais être exposée au navigateur. - Client non connecté : les deux éléments sont laissés vides (ou absents). Le widget se rend alors en mode non authentifié — il affiche le programme et les récompenses, mais ni le solde, ni l'historique, ni les actions d'échange.
- Langue : le widget choisit sa langue dans l'ordre suivant — langue de la page (
data-enkore-language-iso), puis langue par défaut du store configurée au back-office, puis français. Les langues gérées sontfr,en,es,de,it,nl,pl; un code régional (fr-FR) est ramené à sa langue (fr), etgb— l'iso_codesous lequel PrestaShop installe l'anglais britannique — est traité commeen. - Domaine : en son absence, le widget utilise le domaine du navigateur (
protocol + hostname). L'élément n'est donc utile que lorsque la page est servie sur un domaine différent de celui déclaré chez Enkore (préproduction, domaine multi-boutique).
Exemple de page
<!-- Point de montage -->
<div id="enkore-loyalty-program"></div>
<!-- Identification du client, rendue côté serveur -->
<div id="enkore-loyalty-hash" hidden>708e3f96061caf0af6…</div>
<div id="enkore-loyalty-id" hidden>8924</div>
<!-- Facultatif -->
<div id="enkore-language" hidden data-enkore-language-iso="fr"></div>
<div id="enkore-store-domain" data-enkore-domain="https://monstore.com"></div>
<!-- Chargement du widget -->
<script src="https://program-presentation-widget.enkore.io/enkore-presentation-default-1-0.js"></script>
Comportements pris en charge par le script
- L'emplacement de la page est donné par le point de montage : le widget se rend dans
#enkore-loyalty-program. - Le CSS personnalisé défini au back-office est injecté dans le
<head>sous forme de balise<style id="enkore-custom-css">. Les styles du widget sont préfixés par.enkore-widgetpour ne pas déborder sur la page hôte. - Les identifiants de section (
#enkore-point-system-section,#enkore-redeem-section,#enkore-history-section,#enkore-faq-section) sont stables : ils servent de cibles aux boutons de la bannière et peuvent être ciblés depuis le CSS personnalisé. - Le lien de parrainage est géré automatiquement : si l'URL de la page contient
?referral-hash=…, le widget récupère le code du filleul, l'affiche dans une modale, puis retire le paramètre de l'URL.
Aucun appel HTTP n'est à écrire : le script contacte l'API lui-même, avec les mêmes endpoints que ceux listés ci-dessous.
Intégration par API
Une boutique qui souhaite construire son propre affichage appelle directement les endpoints de l'API. Chaque endpoint est décrit — paramètres, schémas de réponse, exemples de code — dans la référence d'API.
Au chargement de la page
| Endpoint | Rôle | Authentification |
|---|---|---|
GET /store/widget/program-presentation | Configuration visuelle et textuelle de la page telle que définie au back-office (sections, couleurs, textes, CSS personnalisé, traductions) | domain |
GET /point/user-history/{externalId} | Solde de points du client, historique des mouvements encore valides et palier de club | domain + hash |
GET /reward/list | Récompenses de la boutique et nombre de points requis pour chacune | domain |
L'appel de configuration n'a d'intérêt que si l'on souhaite piloter l'apparence de la page depuis le back-office Enkore. Une intégration entièrement maîtrisée côté boutique peut s'en passer.
Sur action du consommateur
| Endpoint | Rôle | Authentification |
|---|---|---|
POST /reward/claim/{externalId} | Échange les points du client contre une récompense et retourne le code de réduction à afficher | domain + hash |
POST /point/referral | Enregistre le parrainage d'un ami à partir de son email et retourne le hash de parrainage à diffuser | domain + hash |
POST /reward/referral/get-referee-code | Côté filleul : échange le hash de parrainage lu dans l'URL (?referral-hash=…) contre son code de réduction | Aucune |
Le dernier endpoint n'est à implémenter que si le parrainage de la boutique est de type "bon d'achat".
Authentification
Les endpoints qui opèrent au nom d'un client (hash) exigent les paramètres domain, externalId et hash — voir Authentification par hash. Les autres n'ont besoin que du paramètre domain et sont publics.
Quelle intégration choisir ?
Par défaut, l'intégration par script. Elle demande moins de travail : il suffit d'exposer quelques éléments dans le HTML et de charger le script. Elle donne accès à la configuration de la page depuis le back-office Enkore, et la boutique profite automatiquement des mises à jour du widget — nouvelles sections, corrections, nouvelles langues — sans redéploiement de son côté.
L'intégration par API est réservée aux boutiques qui veulent un contrôle total de l'affichage : intégration profonde dans un design system, parcours sur mesure, framework front spécifique. En contrepartie, tout le rendu et son évolution restent à la charge de la boutique.