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 |
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
