This documentation provides details on how to transmit information to the campaign games made with Adictiz Box in a safe way. This method is based on the JSON Web Token (JWT).

Examples

Transfer personal data to the campaign games so that it can then be used to personalize the participant's game path (access to the game following the completion of a purchase, for example, or pre-filling a form).
Authenticate a participant upon their arrival onto the campaign game: allows for the display of a campaign game with the player already authenticated upstream.
Authenticate a player during the campaign game (SSO): allows for the display of a "Play" button that authenticates the player at any stage of the game.

These last 2 examples make it possible to anonymize the personal data of the players who are hosted by Adictiz.

What is a JSON Web Token?

It is an open standard (RFC7519) that allows you to securely transmit information between parts as a JSON object in a compact and self-contained manner. This information can be verified and approved because it is digitally signed. JWTs can be signed using a secret key (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.

Although JWTs can be encrypted to also ensure secrecy between parties, we will focus on signed tokens.

Glossary

Brand or customer: This is the customer subscribing to Adictiz Box who sets up the campaign games.
Participant: These are the users who participate in the campaign games set up by the brand.

Prerequisites

Private key (unique to the campaign game): Available directly in the editor Advanced settings in the "Campaign Settings" section.

Private key (global to the client account): this makes it possible to run JWTs on several campaigns simultaneously (recommended if used for an SSO). To obtain it, contact your Account Manager (recommended)

⚠️ If the campaign private key is created, then the account private key can no longer be used for that campaign.

Exchanging data with Adictiz Box campaign games

Authentication data (required)

To authenticate and/or transmit participant information in the campaign game, a unique user ID must be sent to the campaign. This can be the user ID used in your IT service, a random identifier, or an email, as long as this value is unique and does not change between the different connections of the same participant.

This login is required and must be sent by using the "partnerUserID" variable (please pay attention to the case) and be transfered through the JWT standard.

Other data

It is also possible to send additional data about the participant in order to identify them, personalize their playing path, and/or use their information in the campaign's data exports.

You can use the 'User' data standardization within Adictiz Box if you want the data to go up in the associated fields within the platform:

Wording	Adictiz standardization	Type	Format
Civility	civility	Listing	String (mr/miss/mme)
Name	lastname	Text - Letter only	String
First name	firstname	Text - Letter only	String
E-mail	email	Email	String (Certified email format)
Address	address	Text - All characters	String
Address complement	add_address	Text - All characters	String
Street	street	Text - All characters	String
Street number	street_number	Text - All characters	String
Birth date	birthday	Date	Euro (DD/MM/YYYY) & EN (YYYY-MM-DD)
Phone number	deskPhone	Text - Figure only	String
Mobile	mobilePhone	Text - Digits only	String
Loyalty number	loyalty	Text - All characters	String
Rules	rules	Opt-in	Int (0/1)
Newsletter	newsletter	Opt-in	Int (0/1)
Optin Mobile	opt-in_mobile	Opt-in	Int (0/1)
Partner Newsletter	opt-in_partner	Opt-in	Int (0/1)
State	state	Text - Letter only	String
Pseudo	nickname	Text - All characters	String
Shop	pointofsale	Text - All characters	String

It is possible to access the custom field - custom_n . n being the n'th custom field created.

Use Cases 1 and 2 - Data transmitted by JWT in the 1st stage of a game campaign

Check the validity of the JWT and use its contents

You can test on your campaign that the JWT signature is valid and use its content to create custom game scenarios for your participants with a Redirector module. To do so :

Add a Redirector module on the first page of your campaign.
Once the module is added, configure the module like this :

You have to create and configure in addition 2 separate pages:

a page of redirection if the JWT is valid ("So go to")
a redirection page if the JWT is not valid ("Otherwise go to").

These 2 pages allow you to redirect your participants according to the validity of their JWT. Your Redirector is now correctly configured, after publishing, you can access the campaign via its link by adding your JWT via its parameter (ex: [https://adbx.io/[unique-name]?jwt=[token]).

Connection process for setting up an SSO via JWT

The functional steps performed by the participants:

The participant goes on the campaign game
He clicks the "Play" button (SSO widget accessible in the editor's widget menu)
He is redirected to a full page or pop-up to the brand login page (login web page & customer account creation) according to what will be set in the campaign on Adictiz Box.
The participant authenticates or creates an account.
He is then redirected to the campaign game in a completely transparent way.

Steps and exchanges with the campaign game

In terms of integration, just follow the JWT implementation method and redirect the participant to the URL received as input, namely https://adbx.io/?jwt=[jwt-generated-by-the-client]

Please note, the JWT must contain in its payload a unique value associated with the 'partnerUserID' parameter (the user's identifier).

Examples of codes integrating the partnerUserID and email:

//Using the https://github.com/firebase/php-jwt 

use \Firebase\JWT\JWT;

//retrieve user data by partner
$partner_user_id = $_SESSION['partner_user_id'];
$partner_email = $_SESSION['partner_email'];

//retrieve the redirection URL sent by the Adictiz Box campaign
$redirect_to = $_GET['redirect_to'];

//generation of JWT with variables
$data = ["partnerUserID" => $partner_user_id,  "email" => $partner_email];
$jwt = JWT::encode($data ,"PRIVATE_KEY_ADICTIZ_BOX");

//redirection to the campaign with the JWT
header('Location:'.$redirect_to."?jwt=".$jwt);

How to test your JWT?

You can generate a JWT directly on the www.jwt.io website, on which you will find a tool to:

generate a valid JWT with the payload and the secret key
see the contents of the payload with the JWT

Tutorial - Redirector

The Adictiz glossary

Push Optin

What you need to know before starting a campaign

Practical Guide to Opt-in