Auto login API

This article is directed at developers who want to integrate an Easypromos campaign inside their website or mobile app.

 

1. Introduction

The auto login API allows sending and registering participants in a promotion directly from a mobile app or a website. It also allows recovering a session from a participant that registered previously.

This API is used to limit participation in the campaign to users that are registered in the client's systems, for example, users registered in your website or users of your mobile app.

The users can only participate in the promotion within your website or inside the mobile app after identifying with their user credentials. The auto login API registers the user before showing the participation mechanic. This way, the user experience is 100% integrated into your website or your app, and the users don't have to fill in their data again to participate.

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

This article includes:

  1. Introduction
  2. Requirements
  3. General technical operation
  4. Server side API and authentication method
  5. Client side API (Javascript) and authentication method
  6. API parameters description
  7. API responses
  8. Use of the participant access code
  9. API error codes

 

2. Requirements

  • The auto login API is only available for clients that have an active White Label or a Corporate plan.
  • The integration with the auto login API should be built by the developer of the website or the mobile app where the promotion is to be shown.
  • The auto login API is currently limited to these Easypromos apps:
    • Puzzle, Memory, Match It, Wordsearch and Hidden Objects.
    • From May 10, 2020 also: Spin the Wheel, Entry Form Giveaway, Distribute Coupon Codes, Redeem Codes and Instant Win.
  • The API is available to be called from a server (Server side API) or from browser's client via Javascript (Client side API). Server side API is recommended.
  • The promotion that is to be integrated needs to be activated and within the dates for publication.
  • The promotion should have the login system enabled.
  • The developer needs the link to the promotion. The link will look like this: https://a.cstmapp.com/p/{promotion_id}
  • If you want to embed the promotion on the website with the widget, the developer needs the widget code. Instructions to obtain the widget code.

(*) If the developer doesn't have some of this information, they should contact the administrator or the creator of the promotion.

 

3. General technical operation

The web developer makes a call to the auto login API and sends the information of the user that wants to participate in the promotion. If the call is valid, Easypromos will respond with a unique access code for this participant. This access code is a valid user session in the promotion.

The developer will use the access code together with the URL of the promotion to show the campaign in the web or app. How will it be shown?

For campaign integrated in mobile app:

  • After making the API call, the developer will open a webview with the URL of the promotion passing the unique access code received from the API as a GET parameter.

For campaign integrated in a website:

  • After making the API call, the developer will redirect the user to an internal web page where the widget of the promotion will be embedded.  The unique access code received from the API will be passed as a parameter in the widget. The Widget loads an iframe with the URL of the promotion.
  • Instead of a widget/iframe embedded on the website, it's also possible to show a banner or a link with the URL of the promotion and passing the unique access code as a GET parameter.

Outline of a campaign with auto login integrated into a mobile app:

autologin_mobileapp.png

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

autologin_website.png

 

4. Server side API and authentification method

The call to the auto login method is a part of the Easypromos REST API. You will find the REST API and auto login method documentation here.

Example:

curl 
--location
--request POST 'https://wl.easypromosapp.com/api/autologin/885667' 
--header 'Authorization: Bearer access_token' 

 

5. Client side API (Javascript) and authentication method

Recommendation: try to use the server side API because it is more secure than the client side API .  

The Server and Client side API share the same parameters and the same error codes. The difference is the URL call and the authentication method.

  • Client Side Auto login call URL: https://wl.easypromosapp.com/api/js/autologin/:promotion_id
  • Method: POST
  • DO NOT INCLUDE access tokens in the call
  • Authentication is done via domain origin. The administrator of the promotion has to add the origin domain to the list of permitted domains (add full subdomain without https):

mceclip0.png

 

Example of Javascript call using jQuery :

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

 

6. API parameters description

The parameters should be sent in POST format and are the following:

Name Type Mandatory Description
external_id string 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.
fname string yes User's first name.
lname string yes User's last name.
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.
skip_registration number no

Values: 0 (false) 1 (true)

Default value: 1

If this parameter is set and it is 0, the users will be required to complete a registration form the first time they participate. It is useful if you want to force the users to accept the terms and conditions or a new opt-in. You can also use it to request extra information before participating.

 

7. API responses

The API responds with a JSON string with these parameters:
  • status: 0 or 1
    • If the value is 0, there was an error. See list of errors.
    • If the value is 1, the user is correct and you have received the corresponding access code.
  • It: a string of characters that corresponds to the value of the user's unique access code. You should use this access code to show the promotion with a user session already created.
  • registered: true or false
    • If the value is 'true', it means that it's the first time this user accesses the promotion and therefore, their data is registered. It's the value of 'external_id' that is used to identify the unique user.
    • If the value is 'false', it means that this user was already registered. It's the value of 'external_id' that is used to identify the unique user.

 

Response example:

HTTP/1.1 200 OK

{
    "status"1,
    "registered"false,
    "lt""$5$dGF7emr9XUTj6FtE$OIvjiheTCL1y6MInRQIlZQWpYUQFQhiUS75i5"
}

 

8. Use of the participant access code

If the response to the call is correct (status = 1), the parameter "It" is included. It is an alphanumeric string that represents the participant's access code.

This code is unique for each participant and when it's passed as a parameter in the promotion link, a user session is created in the promotion, using the field external_id as unique identifying value, and the first name and the last name to show the participant in the promotion.

The way to pass the access code to the promotion is adding the GET parameter named "It" with the value of the access code to the URL of the promotion.

Example:

  • If the URL of the promotion is https://a.cstmapp.com/p/898865
  • The value of the It parameter in the API response is: $$xx555666hsgaf$3!qq2
  • This link should be created to send the user to the promotion with the session created:
    https://a.cstmapp.com/p/898865?lt=$$xx555666hsgaf$3!qq2

Use this URL to load the webview in a mobile app, or to embed an iframe on a website, or generate an access link to the promotion.

If you use the Easypromos embed promotion widget, you should add the It parameter to the "gets" variable of the widget code.

Example of widget code with It 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 code for the widget can be obtained from the promotions management page. Instructions to obtain the code to embed the widget.

 

9. API error codes

In case the call has an error, the status value of the response will be 0 and it will return the error code.

Example of response with error:

HTTP/1.1 200 OK

{

    "status"0,
    "registered"false,
    "reason""external_id"
}

The "reason" field will explain the motive of the error.

The possible error codes are:

errors.token.invalid The access token is invalid
errors.token.no_permissions The access token doesn't have permissions
errors.invalid_domain The domain is not valid for the Client side API call
errors.no_token Access tokens are not permitted for the Client side API call 
errors.external_id External_id parameter is missing or is empty
errors.fname Fname parameter is missing or is empty. User's lastname is mandatory.
errors.lname Lname parameter is missing or is empty. User's lastname is mandatory.
errors.promotion_id Invalid promotion id
errors.bad_parameters One or some parameters are wrong
errors.unexpected_error Unexpected error
errors.promotion_not_activated Promotion is not active
errors.promotion_expired Promotion has expired
errors.promotion_not_white_label Promotion must be white label
errors.promotion_not_open Promotion must be published
errors.promotion_not_login Login is not enabled

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.