API de auto login

 

Este artículo está dirigido a programadores que integrarán una campaña de Easypromos dentro de su página web o dentro de su aplicación móvil.

 

1. Introducción

La API de auto login permite registrar participantes a la promoción de forma programada desde una app móvil o un sitio web. También permite recuperar una sesión de participante que ya se registró previamente.

Esta API se utiliza para limitar la participación a la campaña a usuarios registrados en los sistemas del cliente. Por ejemplo: limitar la campaña a usuarios registrados en tu sitio web o usuarios de tu aplicación móvil.

Los usuarios únicamente podrán participar en la promoción dentro de tu sitio web o dentro de tu app una vez se ha identificado con sus credenciales. La API de auto login registrará al usuario antes de mostrarle la mecánica de participación. De esta forma la experiencia de usuario participante es 100% integrada en tu sitio web o app, y no es necesario que se identifique de nuevo con sus datos. 

Si un usuario intenta acceder o participar en la promoción sin estar logueado en tu sistema, será redirigido al sistema de login/registro de tu web, o a la página para descargarse tu app móvil.

El artículo incluye:

  1. Introducción
  2. Requerimientos
  3. Funcionamiento técnico general
  4. Método de la API de servidor y autenticación
  5. Método de la API de cliente (Javascript) y autenticación
  6. Descripción de parámetros de la API
  7. Respuesta de la API
  8. Uso del código de acceso de participante
  9. Códigos de error de la API

 

2. Requerimientos

  • La API de auto login únicamente está disponible para clientes con un plan Marca Blanca o un plan Corporate activo.
  • La integración con la API de auto login deberá realizarla el desarrollador de la página web o aplicación móvil donde se limita la promoción.
  • La API de auto login actualmente está limitada a estos tipo de aplicaciones de Easypromos:
    • Puzzle, Sopa de letras, Relaciona Parejas, Juego del Memory, Objetos ocultos
    • A partir del 10 de Mayo del 2020: Ruleta de premios, Sorteo, Cupones, Momento Ganador, Valida tu Código
  • La API se puede llamar desde el servidor o bien desde el navegador del cliente con Javascript.
  • La promoción a integrar debe estar activa y dentro de las fechas de publicación
  • La promoción debe tener el sistema de Login habilitado
  • El programador debe disponer del enlace de la promoción. El enlace de la promoción será así: https://a.cstmapp.com/p/{promotion_id}
  • En caso que se quiere integrar el widget de la promoción dentro de la web, el desarrollador deberá disponer del código del widget. Instrucciones para obtener el código del widget.

(*) Si el desarrollador no tiene alguno de estos datos debe ponerse en contacto con el administrador o creador de la promoción.

 

3. Funcionamiento General

El desarrollador web realizará una llamada a la API de auto login y enviará la información del usuario que quiere participar en la promoción. Si la llamada es válida, Easypromos responderá con un código de acceso único para ese participante. Este código de acceso es una sesión válida de participante en la promoción.

El desarrollador usará este código de acceso juntamente con la URL de la promoción para mostrar la campaña en su web o en su app. ¿Cómo la mostrará?

En caso de integrar la campaña en una App móvil:

  • Después de realizar la llamada a la API, abrirá un webview en su app con la URL de la promoción pasando por parámetro GET el código de acceso único obtenido de la API

En caso de integrar la campaña en una Web:

  • Después de realizar la llamada a la API, cargará una página web nueva con el widget de la promoción y pasando como parámetro el código de acceso único obtenido de la API. El widget carga un iFrame con la URL de la promoción. El código del widget lo obtendrá del administrador/creador de la promoción en Easypromos.
  • En vez de un widget/iframe incrustado en la web, también se puede mostrar un banner o un enlace con la URL de la promoción pasando por parámetro GET el código de acceso único.

Esquema de una campaña con auto login integrada en una app móvil:

autologin_appmovil__2_.png

 

El funcionamiento en una página web con usuarios logueados es análogo al flujo de la integración en una app móvil:

autologin_webregistro.png

 

La llamada a la API de auto login se puede realizar desde el servidor o desde el navegador de cliente con una llamada de Javascript. 

Recomendación: siempre que sea posible utilizar la llamada de auto login desde servidor porque es más segura.

 

4. Método de la API de servidor y autenticación

La llamada al método de auto login desde servidor está incluída dentro de la REST API de Easypromos. Encontrarás la especificación de la REST API y del método de auto login aquí.

Ejemplo de llamada a la promoción con ID #88566:

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

 

5. Método de la API de cliente (Javascript) y autenticación

Recomendaciónsiempre que sea posible utilizar la llamada de auto login desde servidor porque es más segura. 

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

  • Url de la llamada auto login: https://wl.easypromosapp.com/api/js/autologin/:promotion_id
  • Método: POST
  • NO SE ACEPTAN tokens de acceso en la llamada. 
  • Autenticación, mediante dominio origen. El administrador de la promoción deberá añadir el dominio desde donde se harán las llamadas con la API de Javascript en la opción de dominios permitidos. Se aceptan múltiples dominios. Se debe introducir el subdominio completo, sin protocolo http/https. Esta opción se encuentra dentro del apartado de configuración de Login en el editor de promociones:

mceclip0.png

 

Ejemplo de llamada mediante jQuery a la promoción con ID #885667:

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

 

6. Parámetros de la API

 Los parámetros se deben enviar en formato post, y son los siguientes:

 

Nombre Tipo Obligatorio Descripción
external_id string 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 User's first name.
lname string 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. Respuesta de la API

La API responderá con una cadena JSON con estos parámetros:

  • status: 0 o 1
    • Si el valor es 0, ha habido un error. Ver sección de errores.
    • Si el valor es 1, el usuario es correcto, y se ha obtenido su código de acceso.
  • lt: cadena de caracteres que corresponde al valor del código de acceso único del usuario. Debes utilizar este código de acceso para mostrar la promoción con una sesión del usuario ya creada.
  • registered: true o false
    • Si el valor es true, quiere decir que es la primera vez que este usuario accede a la promoción, y por lo tanto se registra sus datos. Se utiliza el valor de external_id, para identificar de forma única al usuario.
    • Si el valor es false, quiere decir que este usuario ya estaba registrado. Se utiliza el valor de external_id, para identificar de forma única al usuario.

 

Ejemplo de respuesta:

HTTP/1.1 200 OK

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

 

8. Uso del código de acceso de participante

Si la respuesta de la llamada es correcta (status = 1), se incluirá el parámetro "lt" que incluye la cadena alfanumérica del código de acceso del participante.

Este código es único para cada participante, y al pasarlo como parámetro en el enlace de la promoción, se creará una sesión de usuario participante en la promoción, utilizando el campo external_id como valor único identificativo y el nombre y apellido para mostrar el participante en la promoción.

La forma de pasar este código de acceso a la promoción es añadiendo el parámetro lt, a la url de la promoción.

Ejemplo:

  • Si la url de la promoción es https://a.cstmapp.com/p/898865
  • El valor del parámetro lt en la respuesta de la api es: $$xx555666hsgaf$3!qq2
  • Se deberá generar este enlace para enviar al usuario a la promoción con la sesión ya creada:
    • https://a.cstmapp.com/p/898865?lt=$$xx555666hsgaf$3!qq2

 

Utiliza esta URL para cargar un webview en una app móvil, o incrustar un iframe en una web o generar un link de acceso a la promoción.

En caso de utilizar el widget incrusta de Easypromos, añade el parámetro lt en la variable "gets" del widget.

Ejemplo de código de widget pasando el parámetro lt:

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

 

El organizador puede obtener el código del widget de la promoción desde el gestor de la promoción. Instrucciones para obtener el código del widget.

 

9. Códigos de error de la API

En caso que la llamada tenga algún error, el valor de status en la respuesta será 0, y vendrá el código de error.

Ejemplo de respuesta con error:

HTTP/1.1 200 OK

{

    "status"0,
    "registered"false,
    "reason""external_id"
}
El campo reason tendrá el motivo del error que pueden ser:
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 Javascript API call
errors.no_token Access tokens are not permitted for the Javascript 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
¿Tiene más preguntas? Enviar una solicitud

0 Comentarios

Inicie sesión para dejar un comentario.