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 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.
  • Server Side API: The developer needs an access token to authenticate their access to the API. Instructions to obtain the access token.
  • Client Side API: The origin domain must be included in the allowed domains option in the Login settings of the promotion. How to permit an origin domain.
• 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:

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

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.

• Server Side Auto login call URL: https://wl.easypromosapp.com/api/autologin/:promotion_id
• Method: POST
• To authenticate the API call, include the header Authorization: Bearer access_token . Instructions to obtain an access token

Example:

curl 
--location 
--request POST 'https://wl.easypromosapp.com/api/autologin/885667'
--header 'Authorization: Bearer access_token'
--form 'external_id="uid_112233"'
--form 'fname="John"'
--form 'lname="Smith"'
--form 'nickname="jsmith79"'
--form 'email="john.smith@example.com"'

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

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:

curl 
--location 
--request POST 'https://wl.easypromosapp.com/api/autologin/885667'
--header 'Authorization: Bearer access_token'
--form 'external_id="uid_112233"'
--form 'fname="John"'
--form 'lname="Smith"'
--form 'nickname="jsmith79"'
--form 'email="john.smith@example.com"'

HTTP/1.1 200 OK

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

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

HTTP/1.1 200 OK

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