Autologin system is used to send users already identified in an external system to an Easypromos campaign, allowing them to skip the login and registration process of the promotion itself.

Users will only be able to participate in the promotion within your website or within your app once they have identified themselves with their credentials. In this way, the participating user experience is 100% integrated into your website or app.

The present tutorial is organized as follows:

1. Introduction

2. General technical operation

3. Step 1: Configuration of the promotion to enable the Autologin system

4. Step 2: Programming the Autologin integration with the Easypromos REST API

4.1 API reference documentation
4.2 Request Format

1. API base URL and POST method

2. Authorization

3. Input parameters

4.3 Response Format

1. OK Answer - Status 200

2. Errors

4.4 How to use the User Login Token to forward users to the promotion

4.5 Autologin API from client (Javascript)

4.6 Obsolete Autologin version

5. Troubleshooting guide

6. Report API errors 

 

1. Introduction

The Autologin system is used to send users already identified in an external system to an Easypromos campaign, allowing them to skip the login and registration process of the promotion itself.

Users will only be able to participate in the promotion within your website or within your app once they have identified themselves with their credentials. The Autologin system allows users to register for the promotion via a call to the Easypromos REST API before showing them the participation mechanism. In this way, the participating user experience is 100% integrated into your website or app.

If a user tries to access or participate in the promotion without being identified in your system, they will be redirected to the login/registration system of your website, or to the store to download your mobile app.

Next are presented different cases and examples where the Auto login system can be used:

• Embed a prize wheel promotion within a membership website as a loyalty reward program. Users who log in on the website will be able to access the wheel. Once identified on the web, they will be able to spin the wheel directly, skipping the login/registration process of the Easypromos promotion.
• Show an Easypromos game within a mobile application. Users will participate in the game directly as logged in users within the mobile application.
• Register users to an Easypromos promotion directly from a WhatsApp or Facebook Messenger Bot.
• Give the user the option to try luck in a scratch card to get discounts and prizes just after completing a purchase in an ecommerce. Only users who complete a purchase will have the option to win a prize.

In order to implement the Autologin solution, there is a specific call in the Easypromos REST API. This means that to implement a promotion with Autologin it will be necessary for a computer programmer to integrate a call to the Easypromos REST API.

 

2. General technical operation

The client's web developer will program a call to the Autologin API to send the information of the user who wants to participate in the promotion. If the call is valid, Easypromos will respond with a unique access code User Login Token for that participant. This access code is a valid participant session in the promotion.

The developer will use the User Login Token together with the promotion URL to display the campaign on the website or app.

How will the promotion be displayed?

In case of integrating the campaign in a mobile App:

• After making the call to the APl, a Webview will be opened in your app with the Url of the promotion which will include the User Login Token as a GET parameter.

In case of integrating the campaign on a website:

• After making the API call, a new web page with the promotion Widget will be loaded, passing the User Login Token as a parameter. The widget loads an Iframe with the URL of the promotion. Get the promo widget code.
• Instead of an embedded web widget, you can also direct the user directly to the promotion via a banner or HTML link. The banner or the link must point to the URL of the promotion passing the User Login Token parameter.

Here you can see the workflow of a campaign with Auto Login integrated in a mobile app:

A campaign with auto login integrated into a website would follow the same outline:

 

To have the Autologin solution working, these 2 steps are necessary:

STEP 1 - Configure the promotion from the Easypromos control panel and enable the Autologin system. This step must be carried out by the person who has access to the Easypromos control panel and configures the promotion.

STEP 2 - Program the Autologin integration through the Easypromos REST API. This step must be carried out by the computer programmer of the web, app or system where the promotion is to be integrated.

 

3. Step 1: Configuration of the promotion to enable the Autologin system

To enable the web developer to integrate with the Autologin API, it will be necessary for the promotion administrator to enable the Autologin system in the promotion and in their account. Below we indicate the steps to follow to enable the Autologin.

NOTE: Errors most commonly reported by programmers when integrating the Autologin API are related to the fact that some of the following requirements are not met. Please review the following carefully.

Requirements at the Easypromos account level:

• It is necessary to have an active Corporate plan. Customers with a White Label plan can also ask their sales representative to activate the Autologin system. The activation of the Auto Login feature comes at an additional cost.

Requirements at the promotion level:

1. The promotion must be created in the White Label version. The Autologin system does not work for Premium or Basic promotions.
2. The promotion must be ACTIVE.
3. The promotion must be OPEN. It means that the start date should not be in the future, and the end date should not be in the past.
4. The Autologin solution is NOT available for the following promotion types:
• Photo Contest (Alternatively, the Multimedia Contest can be used)
• Video Contest (Multimedia contest can be used as an alternative)
• Writing Contest (Multimedia Contest can be used as an alternative)
• Photofun Contest (Coming soon Q4 2022)
• Scenes (Coming soon Q4 2022)
• Mention + Hashtag Contest
• Hashtag + Entry Form
• Refer a friend Contest
5. The Autologin system must be activated within the promotion:

If this option does not appear, it means that you do not have a Corporate plan, or the Autologin system is not activated in your promotion. In this case, please contact our team to have it enabled. 

 

The Autologin configuration page includes the options to customize the screen that a user who tries to participate without being identified with the credentials of the external system would see.

The most common case in promotions integrated with Autologin is that a user never arrives at the promotion without being identified with the credentials of the external system. However, there are cases such as (1) that a user directly shares the promotion link to his friends, or (2) that the administrator, instead of communicating the promotion by sending users to his web/app, directly communicates the promotion link promotion,  or (3) that in any way a user discovered the public link of the promotion.

In the event that some users arrive at the promotion without being identified, you will be able to control the behavior when they try to participate:

1. Automatically redirect the user to an external URL (for example, to the Login/Registration URL of your website)
2. Present a screen with personalized texts and direct buttons to the Login/Registration system of your website or to download an app in the Apple Store or Google Play.

Example of the screen for unidentified users trying to participate. They are presented with the buttons to install an app.

  

4. Step 2: Programming the Autologin integration with the Easypromos REST API

This section is aimed at web developers who will integrate users from an external system to an Easypromos promotion through the Autologin API.

 

4.1 API reference documentation

The Autologin API consists of a single POST call to the Easypromos REST API.

This API has been defined according to the Open API 3.1 standard.

Access the reference documentation for the auto login POST call.

 

4.2 Request Format

 

4.2.1 API base URL and POST method

The base URL of the API is:

https://api.easypromosapp.com/v2/users/autologin/{promotion_id}

Where {promotion_id} is a variable that corresponds to the ID of the promotion in which the Autologin solution is integrated.

The API method is POST.

 

4.2.2 Authorization

To authenticate the API call from the server, you'll need to include in the header the Authorization: Bearer access_token. Check out here the instructions to obtain an access token.

Example of an Autologin call with the CURL Authorization HTTP header:

curl -i -X POST \
'https://api.easypromosapp.com/v2/users/autologin/98765' \
-H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

If the request doesn't include a valid access token you will get a 401 error (Unauthorized).

 

4.2.3 Input parameters

Parameters must be sent in JSON format. Therefore the call must include the header:

Content-Type: application/json

The parameters that are accepted are:

Name	Type	Mandatory	Description
external_id	string (255)	Yes	The External ID is the unique identifier for a user. The value can be a string or number. Easypromos always treats it as a string and converts any number value to a string. An External ID should be static. If possible, it should be the same value you use to identify the user in your own system.
first_name	string (255)	no	User's first name.
last_name	string (255)	no	User's last name.
nickname	string (255)	no	User's nickname. Recommended if you don't want to pass the real first name and last name. It must be unique among all participants.
email	string	no	User's email. Add the user's email if you want to send emails from the promotion. It is useful if you want to send automatic emails with coupons, to say thank you, etc.
phone	string (30)	no	User's phone number.
country	string (2)	no	User's country code. Format ISO 3166 Alpha-2 (See list of country codes)
segments	array	no	Optional. List of segments that the user belongs to. It can belong to one or many (Do not send this field, if you don't use segments or the user belongs to none). The segments must be already created in the promotion, organizing brand or the account. Insert the Reference field of the segment. Use them to create participation rules based on user segments. More information about segments.

 

Example of a call to the promotion ID#88566:

curl -i -X POST \
'https://api.easypromosapp.com/v2/users/autologin/88566' \
-H 'Authorization: Bearer <YOUR_JWT_HERE>' \
-H 'Content-Type: application/json' \
-d '{
 "external_id": "7L8-8754-6P8",
 "first_name": "John",
 "last_name": "Smith",
 "nickname": "jsmith",
 "email": "john.smith@example.com",
 "phone": "987-654-889",
 "country": "UK"
}'

 

4.3 Response Format 

4.3.1 OK Answer - Status 200 - User Login Token

If the call is successful, it will respond with an HTTP 200 status and the response will include the content in application/json format.

The response will have the following 2 parameters:

• lt: the chain of characters that corresponds to the user's unique access code: User Login Token. You must use this access code to resubmit the user to the promotion with a user session already created.
• Registered: true or false
• If the value is true, it means that this is the first time that this user accesses the promotion, and therefore their data will be registered. The value of external_id is used to identify in a unique manner the user.
• If the value is false, it means that this user was already registered. The value of external_id is used to uniquely identify the user.

Response example:

HTTP/1.1 200 OK
{
    "registered": false,
    "lt": "$5$dGF7emr9XUTj6FtE$OIvjiheTCL1y6MInRQIlZQWpYUQFQhiUS75i5"
}

4.3.2 Errors

In the following link you can see all the possible errors that the request can return.

 

4.4 How to use the User Login Token to forward users to the promotion

If the call response is correct HTTP Status 200, it will include the lt parameter that contains the alphanumeric string of the participant's access code: the User Login Token.

This code is unique for each participant, and when passing it as a parameter in the promotion link, a user session will be created as a participant in the promotion, using the external_id field as a unique identification value and the first and family names to display the participant in the promotion.

The way to pass this access code to the promotion is by adding the lt parameter to the public link of the promotion.

Example:

• If the public link of the promotion is the following: https://a.cstmapp.com/p/898865
• The value of the lt parameter in the API response is: $$xx555666hsgaf$3!qq2
• The following link must be generated to send the user to the promotion with the session already created:

https://a.cstmapp.com/p/898865?lt=$$xx555666hsgaf$3!qq2 

 

You can use the promotion's public link to load (1) a webview in a mobile app, or (2) embed an iframe on a website, or (3) paint a banner or direct link on your website.

If you use the Easypromos embedded widget, add the lt parameter to the gets variable of the widget.

Widget code example passing the lt parameter:

<!-- Put this div wherever you want in your code. It will contain the widget: -->
<div id="ep_frame_885667" style="width:100%;"></div>

<!-- Add this code at the bottom of your page, right before the <body> closing: -->
<script type="text/javascript" src="https://wl.easypromosapp.com/widget/widget_embed_adaptable.js?v=1.93"></script>
<script type="text/javascript" src="https://wl.easypromosapp.com/js/jquery.ba-postmessage.js?v=1.93"></script>
<script type="text/javascript">
if(typeof(EasyEmbedAdaptable) !== "undefined") {
  EasyEmbedAdaptable.init({
    container_id:"ep_frame_885667",
    domain:"https://wl.easypromosapp.com/",
    gets:"lt=$$xx555666hsgaf$3!qq2&micro=1&utm_source=widget&utm_medium=embed",
    max_height:"100%",
    promo_id:885667
  });
}
</script>

The promotion administrator can get the promotion widget code from the promotion manager. Find here the instructions to get the widget code.

 

Advanced: The User Login Token can be used as an input parameter for some REST API calls, such as registering a new promotion entry.

 

4.5 Autologin API from client (Javascript)

IMPORTANT NOTE: whenever possible, use the Autologin call from the server because it is more secure. REST API calls directly from a browser can carry security risks.

La API de servidor y de cliente comparten los mismos parámetros y los mismos códigos de error. Únicamente se diferencian por la URL de la llamada a la API y el método de autenticación:

The server and client API share the same parameters and the same error codes. They only differ in the URL of the API call and the authentication method:

• Url of the Autologin call: https://api.easypromosapp.com/v2/users/autologinjs/:promotion_id
• Method: POST
• Authorization:
  • Access tokens are NOT ACCEPTED on the call.
  • By source domain: The promotion administrator must add the domain from which the Javascript API calls will be made in the allowed domains option. Multiple domains are accepted. The complete subdomain must be entered, without the http/https protocol. This option is found within the Login configuration section in the promotions editor:

Example of a jQuery call to the promotion with ID #885667:

$.post(
  "https://api.easypromosapp.com/v2/users/autologinjs/885667",
{ 
  external_id: "my_user_id",
  fname: "John",
  lname:"Smith"
}, function(data) {
   console.log(data);
});

4.6 Obsolete Autologin version (version 1.0 prior to April 2022)

IMPORTANT NOTE: This version is obsolete as of April 1, 2022 and will stop working as of April 1, 2023. If you currently use this version, you must migrate your calls to the Autologin system described in this tutorial.

The deprecated version 1.0 specification is available here.

 

5. Troubleshooting guide

5.1 I get an error when I make the API call. What could it be?

All errors returned by the API come with an error code and a descriptive phrase for the error. Try capturing this error code in your program to identify the source of the problem and resolve it. All error codes are documented here: Error list.

If after analyzing the error, you cannot resolve it, you should verify that all of the following requirements are met:

A) At the Easypromos account level:

• The Easypromos account organizing the promotion must have an active Corporate plan or the Autologin system enabled.

B) At the promotion level:

• The promotion must be ACTIVE (not in draft, not expired, not in test mode)
• Promotion must be OPEN (past start date, future end date)
• The Autologin system in the promotion must be enabled. (Editor > Login and Registration)
• The type of promotion must support Autologin

C) At development level:

• The request method must be POST
• The base domain of the call is: https://api.easypromosapp.com
• The call includes the Authorization header with a bearer token.
• The access token belongs to the account that created the promotion
• The access token is not expired
• User information is sent in JSON format
• The information sent includes the external_id parameter  

A frequent error is to receive error code 40 (External id missing or invalid) when you are passing the external_id parameter. In this case the problem is that the JSON format is invalid, and the external_id is not found. Check and validate the syntax of the JSON sent.

 

5.2 After making the Autologin call, and redirecting the user to the promotion with the User Login Token, the dynamic of participation is not displayed, but rather a page that tells the user to register. What's going on?

This case occurs when the system cannot create the participant's session in the user's browser through a cookie. For promotions with Autologin, it is necessary to use cookies. If the user's browser blocks cookies, users will not be able to participate.
A frequent case is when the promotion is embedded as a widget or iframe in a website, and the iframe and the website do not share the same domain. In this case, if the browser has third-party cookies blocked, the participant's session cannot be initialized. It will be necessary to configure the promotion so that it has the same web domain where it is embedded. Check out more information here.

 

6. Report API errors

If you detect any errors in the API, please send an email to support@easypromosapp.com.