Auto login API Follow
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:
- Introduction
- Requirements
- General technical operation
- Server side API and authentication method
- Client side API (Javascript) and authentication method
- API parameters description
- API responses
- Use of the participant access code
- 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'
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:
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 | no | User's first name. |
lname | string | no | User's last name. |
nickname | string | no | User's nickname. Recommended if you don't want to pass the real first name and last name. |
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
- 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µ=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.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 |
Comments
0 comments
Please sign in to leave a comment.