1. Introducción

El sistema de Autologin se utiliza para enviar usuarios de un sistema externo a una promoción de Easypromos, para que los usuarios participen directamente en la dinámica de la campaña (ruleta, juego, sorteo, quiz...) saltándose el proceso de login y registro propio de la promoción.

Los usuarios podrán participar en la promoción desde dentro de tu sitio web o desde dentro de tu app una vez se han identificado con sus credenciales. El sistema Autologin permite registrar a un usuario a la promoción vía una llamada a la API REST de Easypromos antes de mostrarle la dinámica de participación. De esta forma la experiencia de usuario participante es 100% integrada en tu sitio web o app. 

Si un usuario intentara acceder o participar en la promoción sin estar identificado en tu sistema, se le redirigiría al sistema de login/registro de tu web, o a la página para descargarse tu app móvil.

Éstos son algunos de los casos de uso del sistema de Autologin:

1. Incrustar una promoción de ruleta de premios dentro de una web de membresía como un programa de fidelización. Podrán acceder a la ruleta, los usuarios que hagan login en la propia  web. Una vez identificados en la web, ya podrán jugar directamente a la ruleta, saltándose el propio proceso de login/registro de la promoción de Easypromos.
2. Mostrar un juego de Easypromos dentro de una aplicación móvil. Los usuarios participarán en el juego directamente como usuarios logueados dentro de la aplicación móvil.
3. Registrar usuarios a una promoción de Easypromos directamente desde un Bot de Whatsapp o Facebook Messenger, para validar códigos y ganar premios al instante.
4. Dar la opción al usuario a jugar a un Rasca y Gana para obtener descuentos y premios justo después de completar una compra en un ecommerce. Únicamente los usuarios que terminan una compra tendrán la opción de ganar un premio.

Para poder implementar la solución de Autologin, existe una llamada específica a la API REST de Easypromos. Esto quiere decir que para implementar una promoción con Autologin será necesario que un programador informático integre una llamada a la API REST de Easypromos.

Este artículo incluye:

1. Introducción
2. Funcionamiento general
3. Paso 1: Configuración de la promoción para habilitar el sistema Autologin
4. Paso 2: Programar el sistema Autologin con la API REST de Easypromos
   1. Documentación de referencia
   2. Formato de la petición
      1. Url base y método
      2. Autorización
      3. Parámetros de entrada
   3. Formato de la respuesta
      1. Respuesta OK - Status 200
      2. Errores
   4. Uso del User Login Token para redirigir los usuarios a la promoción
   5. API de Autologin desde cliente (Javascript)
   6. Versión obsoleta de Autologin (versión 1.0)
5. Guía de resolución de problemas frecuentes
6. Reportar errores de la API

2. Funcionamiento general

Un desarrollador de la web o de la aplicación donde se quiere integrar el sistema de Autologin, deberá programar una llamada a la API de Autologin para enviar la información de los usuarios que quieren participar en la promoción. Si la llamada es válida, Easypromos responderá con un código de acceso único User Login Token para ese participante. Este código de acceso es una sesión válida de participante en la promoción.

El desarrollador usará el User Login Token juntamente con la URL de la promoción para mostrar la campaña en su web o en su app saltándose la pantalla de Login y Registro propio de Easypromos.

¿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 e incluirá el User Login Token como parámetro GET.

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 User Login Token. El widget carga un iframe con la Url de la promoción. Obtener el código del widget de la promoción.
• En vez de un widget incrustado en la web, también se puede reenviar al usuario directamente a la promoción a través de un banner o un enlace HTML. El banner o el enlace deben apuntar a la Url de la promoción pasando el parámetro User Login Token

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

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

Para hacer funcionar la solución de Autologin es necesario realizar estos 2 pasos:

1. PASO 1 - Configurar la promoción desde el panel de control de Easypromos para habilitar el sistema de Autologin. Este paso lo debe realizar la persona que tiene acceso al panel de control de Easypromos y configura la promoción.
2. PASO 2 - Programar la integración de Autologin a través de la REST API de Easypromos. Este paso lo debe realizar el programador informático de la web, app o sistema donde se quiere integrar la promoción.

3. Paso 1: Configuración de la promoción para habilitar el sistema Autologin

Para que el programador web pueda realizar la integración con la API de Autologin, será necesario que el administrador de la promoción habilite el sistema de Autologin en la promoción y en su cuenta. A continuación indicamos todos los pasos que el administrador deberá realizar.

NOTA: Los errores que habitualmente reporta un programador al integrar la API de Autologin están relacionados en qué algunos de los siguientes requerimientos no se cumplen. Por favor revísalos con atención. 

Requerimientos a nivel de cuenta de Easypromos (1):

1. Es necesario tener un plan Corporate activo. Los clientes con plan Marca Blanca, también pueden solicitar a su representante comercial la activación del sistema Autologin con un coste adicional.

Requerimientos a nivel de promoción (5):

1. La promoción debe ser versión Marca Blanca. El sistema Autologin no funciona en promociones Premium o Básicas.
2. La promoción debe estar ACTIVA.
3. La promoción debe estar ABIERTA. Quiere decir que la fecha de inicio no es futura, y la fecha de fin no es pasada.
4. La solución de Autologin NO está disponible para los siguientes tipos de promoción:
   • Concurso de reclutadores
5. Se debe activar el sistema Autologin dentro de la promoción:

Si no te aparece esta opción, quiere decir que no tienes un plan Corporate, o el sistema Autologin no está activado en tu promoción.

La pantalla de configuración de Autologin presenta las opciones para personalizar la pantalla que vería un usuario que intentara participar sin estar identificado con las credenciales del sistema externo. 

El uso habitual en las promociones integradas con Autologin es que nunca un usuario llegue a la promoción sin estar identificado con las credenciales del sistema externo. Sin embargo, existen casos como (1) que un usuario comparta directamente el enlace de la promoción a sus amigos, (2) o que el administrador en vez de comunicar la promoción enviando usuarios a su web/app, comunique directamente el enlace de la promoción, (3) o que de alguna forma un usuario descubra el enlace público de la promoción.

En caso que un usuario llegue a la promoción sin estar identificado, podrás controlar el comportamiento cuando intente participar: 

1. Redireccionar el usuario automáticamente a una Url externa (por ejemplo a la Url de Login/Registro de una web)
2. Presentar una pantalla con textos personalizados y botones directos al sistema de Login/Registro de tu web o para descargar una app en la Apple Store o en Google Play.

Ejemplo de pantalla para usuarios no identificados que intentan participar. Se les presenta los botones para de instalarse una app.

4. Paso 2: Programar la integración Autologin con la API REST de Easypromos

Esta sección está dirigida a programadores web que integrarán los usuarios de un sistema externo a una promoción de Easypromos a través de la API de Autologin.

4.1 Documentación de referencia de la API

La API de Autologin consiste en una sola llamada POST a la API REST de Easypromos.

Esta API se ha definido según el estándar Open API 3.1.

Acceder a la documentación de referencia de la llamada POST de auto login.

4.2 Formato de la petición

4.2.1 Url base de la API y Método POST

La Url base de la API es:

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

Donde {promotion_id} es una variable que corresponde al ID de la promoción en la que se integra la solución de Autologin.

El método de la API es el POST

4.2.2 Autorización

Para autenticar la llamada a la API desde el servidor, deberás incluir la cabecera Authorization: Bearer access_token. Instrucciones para obtener un access token

Ejemplo de una llamada Autologin con la cabecera HTTP de Autorización mediante CURL:

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

Si no incluyen un token de acceso válido recibirás un error 401 (Unauthorized).

4.2.3 Parámetros de entrada

Los parámetros se deben enviar en formato JSON. Por lo tanto la llamada debe incluir la cabecera:

Content-Type: application/json

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 Formato de la Respuesta 

4.3.1 Respuesta OK - Status 200 - User Login Token

Si la llamada es satisfactoria responderá con un estado HTTP 200 y la respuesta incluirá el contenido en formato application/json.

La respuesta tendrá los siguientes 2 parámetros:

• lt: cadena de caracteres que corresponde al código de acceso único del usuario: User Login Token. Debes utilizar este código de acceso para reenviar el usuario a la promoción con una sesión de usuario ya creada. Ver la siguiente sección para aprender como usar el parámetro lt.
• 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

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

4.3.2 Errores

En el siguiente enlace puedes ver todos los posibles errores que puede devolver la llamada

4.4 Cómo usar el User Login Token para reenviar los usuarios a la promoción

Si la respuesta de la llamada es correcta HTTP Status 200, incluirá el parámetro lt que contiene la cadena alfanumérica del código de acceso del participante: User Login Token.

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 al enlace público de la promoción.

Ejemplo:

• Si el enlace público 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

Puedes utilizar el enlace público de la promoción para cargar (1) un webview en una app móvil, o (2) incrustar un iframe en una web o (3) pintar un banner o un enlace directo en tu web.

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 administrador de la promoción 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.

Avanzado: se puede usar el User Login Token como parámetro de entrada de algunas llamadas a la API REST, como por ejemplo para registrar una nueva participación en la promoción. 

4.5 API Autologin desde cliente (Javascript)

NOTA IMPORTANTE: siempre que sea posible utiliza la llamada de Autologin desde servidor porque es más segura. Las llamadas REST API directamente desde un navegador pueden comportar riesgos de seguridad.

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:

• Url de la llamada auto login: https://api.easypromosapp.com/v2/users/autologinjs/:promotion_id
• Método: POST
• Debe incluir la cabecera Content-type: application/json, y los parámetros se deben pasar en formato jSON.
•  Autorización:
  • NO SE ACEPTAN tokens de acceso en la llamada. No debes incluir la cabecera Authorization.
  • 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. Si se hace una llamada desde un dominio no permitido, el navegador responderá con un error de CORS (cross origin policy).

Los dominios permitidos se añaden dentro del apartado de configuración de Login en el editor de promociones:

Se debe introducir solamente el dominio permitido sin http o https. Puedes poner múltiples dominios, uno por línea.

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

var SendInfo= {'external_id':'7L8-8754-6P5','first_name':'John','last_name':'Smith'};   

$.ajax({
          type: 'post',
          method:'post',
          contentType: "application/json",
          dataType: "json",
          processData: false,
          data: JSON.stringify(SendInfo),
          url: "https://api.easypromosapp.com/v2/users/autologinjs/885667", 
          success: function( data, textStatus, jQxhr ){
            console.log(JSON.stringify( data ));
          },
          error: function( jqXhr, textStatus, errorThrown ){
            console.log( errorThrown );
          }
});

4.6 Versión Autologin obsoleta (versión 1.0 previa Abril 2022)