API de Webhook

Uso: ​El caso de uso principal de la API de Webhook de Almacenamiento de Datos Externos de Labvanced es transferir datos de participantes en “tiempo real” a un servidor externo / remoto, en lugar de alojar los datos grabados en los servidores de Labvanced.

NOTA: ​Contrario a muchos casos de uso de API, lo que se describe aquí NO es cómo llamar a la API / endpoints de Labvanced (tal funcionalidad no existe por ahora), sino más bien cómo debe configurar/implementar su backend, de modo que nuestra plataforma pueda llamar automáticamente a los endpoints que usted ha implementado para enviar los datos de los participantes directamente a su backend/base de datos en lugar del nuestro.

Disponibilidad: ​Esta funcionalidad está disponible únicamente para los titulares de licencias de laboratorio de Labvanced.

1. Configuración de la API de Webhook

Para utilizar la API de Webhook, primero se debe activar la opción de “almacenamiento de datos externos” en “Configuraciones del Estudio” del respectivo estudio de Labvanced en la sección de “Características del Experimento”.

1.1 Parámetros:

• Dirección IP: Ingrese su dirección IP estática donde su servidor externo está funcionando / disponible públicamente.
• Puerto: El puerto que se debe usar para enviar los datos.
• Ruta URL​: La ruta URL que se debe agregar después del puerto. Esto es particularmente útil para “espaciar” sus proyectos / datos entrantes, de modo que los datos de diferentes experimentos se envíen a una ruta URL diferente. La ruta URL es opcional, pero recomendamos encarecidamente usarla.

2. Crear el Servidor / Script para Recibir los Datos de la API de Webhook

Basado en su configuración en el paso 1, debe implementar un servidor que esté disponible en la dirección IP, puerto y ruta URL especificados. Una versión simplificada / ejemplo de tal servidor está disponible en nuestra página de Github aquí.

2.1 Formato de datos: Los datos se envían en formato JSON para todas las rutas excepto para la ruta “/file_upload”. La ruta “/file_upload” (utilizada para subir archivos binarios como videos o audios grabados) está codificada como “multipart/form-data”, así que asegúrese de analizar los datos entrantes correctamente como JSON o multipart/form-data / datos binarios.

2.2. Configuración de CORS: Al implementar su backend, debe implementar / permitir Compartición de Recursos de Origen Cruzado (CORS). En particular, debe establecer los siguientes encabezados: “Access-Control-Allow-Origin” (incluir ​https://www.labvanced.com/​), “Access-Control-Allow-Methods” (incluir POST y OPTIONS), “Access-Control-Allow-Headers” (incluir Content-Type).

2.3 Tipos de solicitudes: ​Todos los tipos de solicitudes son solicitudes POST ya que se utilizan para enviar datos. En este punto, un valor de retorno solo es necesario para la ruta “/file_upload”. Todas las demás rutas no necesitan un valor de retorno especial.

2.4 Tipos de solicitudes / rutas: ​Cada vez que un participante forma parte de un estudio, en total se enviarán 8 diferentes ​tipos​ de solicitudes POST a (su servidor externo). La ruta “/file_upload” solo se usará si su estudio incluye una acción para subir algunos datos binarios grabados (por ejemplo, audio o video). Cada tipo de solicitud POST tiene una ruta diferente (ruta URL), que se agregará a la ruta URL especificada en el paso 1. Además, cada tipo de solicitud tiene una estructura/carga diferente, lo cual debe tener en cuenta al analizar y almacenar los datos. Consulte los detalles en la sección 3.

3. Definiciones de Endpoints / Rutas de la API de Webhook:

A continuación, verá una explicación detallada de cada ruta / endpoint que se utiliza/llama cuando un participante toma parte en el experimento. Idealmente, sugerimos que implemente todos estos endpoints (excepto 3.1), y asegúrese de que todos los datos se analicen y almacenen adecuadamente en su base de datos.

¿Qué endpoints se utilizan, qué servidor se llama cuando?

• El endpoint 3.1 “/startExpPlayer” se envía solo al servidor de Labvanced para cargar la definición del experimento / archivo JSON y estímulos asociados desde nuestro servidor.
• Los endpoints 3.2, 3.3, 3.4, 3.7 y 3.8 se envían tanto al servidor de Labvanced (necesario para el equilibrio de grupos y el flujo general del experimento) como al servidor externo/su.
• Los endpoints 3.5 y 3.6 solo se envían al servidor externo/su. Tenga en cuenta que todos los datos de prueba/participante se envían a través de la ruta 3.6, que por tanto es el endpoint más importante a implementar.
• El endpoint 3.9 solo se envía al servidor externo/su y se llama cada vez que se ejecuta una “acción de carga” para subir datos binarios (audio o video).

3.1 Carga del experimento

• Ruta: /startExpPlayer
• Tipo: POST
• Llamado cuando: El participante visita una cierta URL de experimento en labvanced.com. Función principal en el servidor de Lavanced: Inicializa la carga del experimento.
• Carga útil: JSON con los siguientes campos:

NOTA: No es necesario implementarlo en servidores externos, ya que esto solo inicializa la carga del experimento desde el servidor de Labvanced al computador cliente.

3.2 Selección de grupo y sesión

• Ruta: /startFirstPlayerSession
• Tipo: POST
• Llamado cuando: La ruta 3.1 “/startExpPlayer” devuelve exitosamente desde el servidor de Labvanced.
• Función principal en el servidor de Lavanced: Se utiliza para asignar números de grupo y sesión a un sujeto (equilibrio del lado del servidor).
• Carga útil: JSON con los siguientes campos:

3.3 ​Inicio del experimento

• Ruta: /setPlayerSessionStartedTime
• Tipo: POST
• Llamado cuando: El participante presiona “Iniciar Experimento”.
• Función en el servidor de Lavanced: Guarda el tiempo de inicio, la sesión y el nombre del grupo del experimento y comienza el experimento.
• Carga útil: JSON con los siguientes campos:

3.4 Agregar información de metadatos

• Ruta: /addMetaInfo
• Tipo: POST
• Llamado cuando: El participante presiona “Iniciar Experimento”.
• Función en el servidor de Lavanced: Guarda la información meta en el servidor.
• Carga útil: JSON con los siguientes campos:

3.5 Grabar información sobre una tarea

• Ruta: /recordStartTask
• Tipo: POST
• Llamado cuando: Inicia una nueva tarea en el flujo del experimento.
• Función en el servidor de Lavanced: No se llama cuando se activan las solicitudes de API externas.
• Carga útil: JSON con los siguientes campos:

3.6 Grabar datos de prueba

• Ruta: /recordTrial
• Tipo: POST
• Llamado cuando: Se termina una prueba O se ejecuta una acción de grabación personalizada.
• Función en el servidor de Lavanced: No se llama cuando se activan las solicitudes de API externas.
• Carga útil: JSON con los siguientes campos:

NOTA: Los datos exactos que se registran por prueba dependen del experimento específico y de la tarea. Una visión general para cada estudio está disponible en la pestaña "Variables" del experimento específico (ver captura de pantalla). Tenga en cuenta también que los nombres de las variables de la API externa se utilizarán como clave en la estructura JSON. Por lo tanto, asegúrese de que los nombres de las variables sean únicos. De lo contrario, sobrescribirá los datos. El sistema de Labvanced normalmente obliga al usuario a utilizar nombres de variable únicos.

3.7 Terminar el experimento con éxito

• Ruta: /finishExpSession
• Tipo: POST
• Llamado cuando: El experimento se finaliza con éxito.
• Función en el servidor de Lavanced: Termina el estudio y marca el conjunto de datos como completado (importante para el equilibrio).
• Carga útil: JSON con los siguientes campos:

3.8 Terminar el experimento con fallo

• Ruta: /errExpSession
• Tipo: POST
• Llamado cuando: El experimento es abortado con un error.
• Función en el servidor de Lavanced: Aborta el estudio y marca el conjunto de datos como incompleto.
• Carga útil: JSON con los siguientes campos:

3.9 Subir datos binarios (audio o video)

• Ruta: /file_upload
• Tipo: POST
• Llamado cuando: Se ejecuta una acción de carga en el sistema de eventos asociada con algún objeto de grabación de audio o video. Función en el servidor de Lavanced: No se llama cuando se activan las solicitudes de API externas.
• NOTA: El servidor debe enviar valores de retorno para esta ruta (explicado a continuación). Si esto no se hace, el desencadenador “onUploadComplete” no se ejecuta y el experimento no puede propagarse correctamente. También tenga en cuenta que los datos en esta ruta están codificados como “multipart/form-data” ya que incluye tanto datos binarios como no binarios.
• Carga útil: JSON con los siguientes campos:

Respuesta Requerida: