v1-Basic Integration and Authentication

This document will guide you to set-up basic integration and authentication with Zinrelo Console.

Introduction

Here is a video to guide you through integrating the Basic Integration Snippet:

The basic API integration and authentication snippet serves two purposes:

  • Member Enrollment: It passes the information of the user logged-in on your website to Zinrelo so that Zinrelo can authenticate the user, initiate a session and log the user into the loyalty program.
  • Load the loyalty dashboard and other resources: This snippet also deploys different resources like the all.js javascript file and other scripts necessary to enable the loyalty dashboard and functions required for the loyalty program.

Where to find the snippet?

A customized basic integration and authentication code snippet for your account is available in your Zinrelo Admin Console in the ‘General’ tab under ‘Integration’.

basic Integration

How to include the snippet?

Add the snippet into the HEAD section of your website page template so that this snippet appears on ALL pages of your website. The JavaScript snippet looks like this:

<script type="text/javascript"> 

  window._zrl = window._zrl || [];
 
  var init_data = { 
     'partner_id' : '22ee49123b', 
         /*REQUIRED: Partner ID*/
     
     'email' : '[email protected]', 
         /*REQUIRED: When User is Logged in.For Non-Logged in users,   
          pass an empty string ('')*/

     'name' : 'User Name', 
         /*REQUIRED: When User is Logged in.For Non-Logged in users, 
          pass an empty string ('')*/ 

     'user_id' : 'Unique-user-ID', 
        /*REQUIRED: When User is Logged in.For Non-Logged in users 
          and guest users who DO NOT have an account, pass an empty 
          string ('')*/ 

     'ts' : 'Current TimeStamp in epoch format', 
       /*REQUIRED : Timestamp in epoch format'*/

     'access_token' : 'acafb9c8d189b55671b5956bd75b33ee2e982b89ef42f3b26421f6d8f7fe4872'
      /*REQUIRED : 'SHA256 hash of the string formed by concatenating
       - user_id, email,partner_id, api_key and ts - in the same 
       order as mentioned' */

   }; 

 _zrl.push( [ 'init' , init_data ] ); 

</script> 

<script src="//cdn.zinrelo.com/js/all.js" type="text/javascript"></script>

Populate the following fields dynamically: ‘partner_id’, ‘email’, ‘name’, ‘user_id', 'ts', 'access_token'. These fields contain end-user information – email, user full name and user_id – and the rest of the fields - 'ts' and 'access_token' are required for ensuring the security and integrity of the data passed.

For a logged in user, these must be filled dynamically wherever available. For a guest/non-logged in user, you can simply pass the 'partner_id' and pass empty string ('') for the rest of the values.

If only the user_id field is not available to Zinrelo on a particular page, it is still assumed that the customer is not logged in to the website and will be logged out of the loyalty program too.

Shown below is the detailed description of the fields to be populated dynamically. All fields are required and must be populated for the loyalty rewards program to work.

  • partner_id: This is an alpha-numeric value assigned that uniquely identifies your account in Zinrelo. You can find your Partner ID in Zinrelo Admin Console > General > Settings section . If you have any trouble getting your Partner ID, please contact our Customer Success Manager or email [email protected]
  • email: This is the email address of the user who is logged in to your website e.g - [email protected] . Zinrelo uses this email address to identify a user record in Zinrelo database. It is used to associate loyalty transactions and to communicate with and re-engage the user.
  • name: This is the full name of the user who is logged in to your website. This information is used to address the user on the loyalty rewards dashboard and to include in the email templates sent to the user.
  • user_id: This is the unique identifier of the user in your database. Zinrelo uses this ID as an additional identifier for the user.
  • ts: This is the current timestamp in unix epoch format. For e.g 1602058996.
  • access_token: This is the SHA256 hash of the string formed by concatenating - user_id, email, partner_id, api_key and ts - in the same order as mentioned. This will be string with 64 characters. When Zinrelo receives all the above values , it generates its own SHA256 hash with the API key from your account and matches it with the access_token you passed. This is to verify the authenticity of the data. In order to generate access_token, you will need an API key. You can find your API Key in Zinrelo Admin Console > General > Settings section just below the Partner ID. If you have any trouble implementing the logic to generate access_token, please reach out to [email protected]
  • Please note that you do not share your API key with anyone or anywhere. It should be used only in the backend systems.
  • language: This is the multi-language option we provide to members. They can list the languages in which they want their dashboard to be.
  • tags:. Multiple comma separated tags can be assigned to the member. The tags passed through the script are appended to the existing tags the member may have. Tags are useful to apply business rules and filter the members to run campaigns.

Note: Since you would never want to expose your API Key on the frontend, you will need to generate the access_token at the backend and relay it over to the frontend so that it can be passed in the Zinrelo JavaScript snippet.

Common Mistakes

Here are some common mistakes in including the Basic Integration Snippet:

  • Partner ID is copied as-is from this document: The partner_id field is a unique key generated by Zinrelo to identify a Client. Please confirm that your partner_id is correct. If you are copying code from the Zinrelo Admin Console, the partner_id will be correct. If you are copying as-is from this document, the partner_id will be wrong.
  • Integration snippet is copied as-is: The fields must be filled dynamically from the information available on the website. Therefore, a developer with some technical skills is required to complete this task. It is not a mere copy and paste.
  • All.js code is not copied onto the website: Zinrelo uses a Javascript called all.js. This script must be included in the snippet.