Cette documentation permet de détailler comment transmettre des informations aux campagnes de jeux réalisées avec Adictiz Box de manière sécurisée. Cette méthode s'appuie sur des JSON Web Token (JWT).

Cas d’usage

Transmettre des données personnelles à la campagne de jeu afin que celles-ci soient ensuite utilisées pour personnaliser le parcours de jeu du participant (accès au jeu suite à la réalisation d'un achat par exemple ou pour pré-remplir un formulaire).
Authentifier un participant à l'arrivée sur la campagne de jeu : permet d'afficher une campagne de jeu avec le participant déjà authentifié en amont.
Authentifier un participant pendant la campagne de jeu (SSO) : permet d'afficher un bouton 'Jouer' authentifiant le participant à n'importe quelles étapes du jeu.

Ces 2 derniers cas d'usage permettent notamment d'anonymiser les données personnelles des participants qui sont hébergées par Adictiz.

Qu'est ce qu'un JSON Web Token?

Il s'agit d'un standard ouvert (RFC7519) qui permet de transmettre des informations en toute sécurité entre les parties sous forme d'objet JSON de manière compacte et autonome. Ces informations peuvent être vérifiées et approuvées car elles sont signées numériquement. les JWT peuvent être signées à l'aide d'un secret (avec l'algorithme HMAC) ou d'une paire de clés publique / privée à l'aide de RSA ou ECDSA.

Bien que les JWT puissent être cryptées pour assurer également le secret entre les parties, nous nous concentrerons sur des tokens signés.

Lexique

Marque ou client: il s'agit du client abonné à Adictiz Box qui met en place les campagnes de jeu.
Participant: il s'agit des utilisateurs qui participent aux campagnes de jeu mises en place par la marque.

Pré-requis

Générer une clé privée (unique à la campagne de jeu) en suivant ces étapes :

Cliquez sur le bouton ⚙️ Paramètres
Cliquez sur l'onglet Paramètres avancés 🛠
Cliquez sur l'onglet Clé privée

Clé privée (globale au compte client): cela permet notamment de faire fonctionner des JWT sur plusieurs campagnes simultanément (recommandation si utilisée pour un SSO). Pour l'obtenir, rapprochez-vous de votre Account Manager (recommandé)

⚠️ Si la clé privée au niveau de la campagne est créée, alors celle au niveau du compte n'est plus utilisable pour cette campagne.

Echange de données avec les campagnes de jeu Adictiz Box

Données d’authentification (obligatoire)

Pour authentifier et/ou transmettre des informations d'un participant dans la campagne de jeu, il faut envoyer à la campagne un identifiant unique d’utilisateur. Cela peut être l'identifiant utilisateur utilisé au sein de votre SI, un identifiant aléatoire, ou un email, à partir du moment où cette valeur est unique et ne change pas entre les différentes connexions d'un même participant.

Cet identifiant est obligatoire et doit être envoyé en utilisant la variable “partnerUserID” (attention à bien respecter la casse) et transféré via le standard JWT.

Autres données

Il est aussi possible d’envoyer des données supplémentaires concernant le participant, afin de pouvoir l’identifier, personnaliser son parcours de jeu, et/ou exploiter ses informations dans les exports de données de la campagne.
Vous pouvez utiliser la normalisation des données 'Utilisateur' au sein d'Adictiz Box si vous souhaitez que les données remontent dans les champs associés au sein de la plateforme:

Libellé	Normalisation Adictiz	Type	Format
Civilité	civility	Liste	String (mr/miss/mme)
Nom	lastname	Texte - Lettre uniquement	String
Prénom	firstname	Texte - Lettre uniquement	String
Email	email	Email	String (Certified email format)
Adresse	address	Texte - Tous caractères	String
Complément d'adresse	add_address	Texte - Tous caractères	String
Rue	street	Texte - Tous caractères	String
Numéro de rue	street_number	Texte - Tous caractères	String
Code Postal	zipCode	Texte - Tous caractères	String
Ville	city	Texte - Lettre uniquement	String
Pays	country	Texte - Lettre uniquement	String
Date de naissance	birthday	Date	Euro (DD/MM/YYYY) & EN (YYYY-MM-DD)
Téléphone	deskPhone	Texte - Chiffre uniquement	String
Mobile	mobilePhone	Texte - Chiffre uniquement	String
N° de fidélité	loyalty	Texte - Tout caractères	String
Règlement	rule	Opt-in	Int (0 / 1)
Newsletter	newsletter	Opt-in	Int (0 / 1)
Optin Mobile	optin_mobile	Opt-in	Int (0 / 1)
Newsletter Partenaire	optin_partner	Opt-in	Int (0 / 1)
Etat	state	Texte - Lettre uniquement	String
Pseudo	nickname	Texte - Tout caractères	String
Magasin	pointofsale	Texte - Tout caractères	String

Il est possible d’accéder au champ personnalisé - custom_n . n étant n'ème champs personnalisé créé.

Cas d'usage n° 1 et 2 - Données transmises par JWT en 1ère étape de campagne de jeu

Vérifier la validité de la JWT et utiliser son contenu

Vous pouvez tester sur votre campagne que la signature de la JWT est valide et utiliser son contenu pour créer des scénarios de jeux personnalisés pour vos participants avec un module Redirecteur. Pour cela :

Ajoutez un module Redirecteur en première page de votre campagne.

Une fois le module ajouté, il faut configurer le module comme ceci :

Il faut créer et configurer en supplément 2 pages distinctes:

une page de redirection si la JWT est valide (“Alors aller vers”)
une page de redirection si la JWT n’est pas valide (“Sinon aller vers”).

Ces 2 pages permettent de rediriger vos participants en fonction de la validité de leur JWT. Votre Redirecteur est maintenant correctement paramétré, après avoir publié, vous pouvez accéder à la campagne via son lien en y ajoutant votre JWT via son paramètre (ex: [https://adbx.io/[unique-name]?jwt=[token]).

Processus de connexion pour la mise en place d'un SSO via JWT

Les étapes fonctionnelles réalisées par les participants :

Le participant se rend sur la campagne de jeu
Il clique sur le bouton "Jouer" (widget SSO accessible dans le menu des widgets de l'éditeur)
Il est redirigé en pleine page ou en pop-up vers la page de connexion de la marque (page web de connexion & création de compte du client) selon ce qui sera paramétré au sein de la campagne sur Adictiz Box.
Le participant s’authentifie ou se créer un compte.
Il est ensuite redirigé vers la campagne de jeu de manière totalement transparente.

Étapes et échanges avec la campagne de jeu

En terme d'intégration il suffit de suivre la méthode d'implémentation de la JWT et rediriger le participant vers l'url reçue en entrée, à savoir https://adbx.io/?jwt=[jwt-généré-par-le-client]

À bien noter, la JWT doit impérativement contenir dans son payload une valeur unique associée au paramètre 'partnerUserID' (l'identifiant de l'utilisateur).

Exemples de codes intégrant le partnerUserID et l'email :

// Utilisation de la lib https://github.com/firebase/php-jwtuse \Firebase\JWT\JWT;

// récupération des données utilisateur coté partenaire
$partner_user_id = $_SESSION['partner_user_id'];
$partner_email = $_SESSION['partner_email'];

// récupération de l'URL de redirection envoyée par la campagne Adictiz Box
$redirect_to = $_GET['redirect_to'];

// génération du JWT avec variables
$data = ["partnerUserID" => $partner_user_id,  "email" => $partner_email];
$jwt = JWT::encode($data, "CLE_PRIVE_CAMPAGNE_ADICTIZ_BOX");

// redirection vers la campagne avec le JWT
header('Location:'.$redirect_to."?jwt=".$jwt);

Comment tester votre JWT ?

Vous pouvez générer des JWT directement sur le site www.jwt.io, sur lequel vous trouverez un outil permettant :

à partir du payload et de la clé secrète: de générer une JWT valide
à partir de la JWT: de voir le contenu du payload