API de Webhook

Uso: ​El caso de uso principal para 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 albergar los datos registrados en los servidores de Labvanced.

TENGA EN CUENTA: ​A diferencia de muchos casos de uso de API, lo que se describe aquí NO es cómo llamar a la API de Labvanced / endpoints (tal funcionalidad no existe por ahora), sino cómo debe configurar/implementar su backend, de manera 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 solo está disponible para los titulares de licencias de laboratorio de Labvanced.

1. Configuración de la API de Webhook

Para usar la API de Webhook, primero debe activar la opción de “almacenamiento de datos externo” 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 debe usarse para enviar los datos.
• Ruta URL​: La ruta URL que debe añadirse después del puerto. Esto es particularmente útil para “espaciar” sus proyectos / datos entrantes, de tal manera que los datos de diferentes experimentos se envían 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

Con base 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 la ruta “/file_upload”. La ruta “/file_upload” (usada para cargar archivos binarios como videos grabados o audio) está codificada como “multipart/form-data”, por lo que asegúrese de que los datos entrantes se analicen correctamente como JSON o multipart/form-data / datos binarios.

2.2. Configuración de CORS: Al implementar su backend, debe implementar / permitir el Compartición de Recursos de Origen Cruzado (CORS). Particularmente, 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 momento, 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 toma parte en un estudio, se enviarán en total 8 tipos diferentes de solicitudes POST a su servidor (externo/suyo). La ruta “/file_upload” solo se utilizará si su estudio incluye una acción para cargar algunos datos binarios grabados (por ejemplo, audio o video). Cada tipo de solicitud POST tiene una ruta diferente (ruta URL), que se añadirá a la ruta URL especificada en el paso 1. Además, cada tipo de solicitud tiene una estructura/carga diferente, que debe tenerse en cuenta al analizar y almacenar los datos. Vea los detalles en la sección 3.

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

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 el 3.1), y se asegure de que todos los datos se analicen y almacenen apropiadamente 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 los 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 balanceo de grupos y el flujo general del experimento) como a su servidor externo.
• Los endpoints 3.5 y 3.6 se envían solo a su servidor externo. Tenga en cuenta que todos los datos de prueba/participante se envían a través de la ruta 3.6, que, por lo tanto, es el endpoint más importante de implementar.
• El endpoint 3.9 se envía solo a su servidor externo y se llama cada vez que se ejecuta una “acción de carga” para cargar 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 Labvanced: Inicializa la carga del experimento.
• Carga: JSON con los siguientes campos:

NOTA: No necesita ser implementado en servidores externos, ya que solo inicializa la carga del experimento desde el servidor de Labvanced hasta la computadora del 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 Labvanced: Utilizada para asignar números de grupo y sesión a un sujeto (balanceo del lado del servidor).
• Carga: 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 Labvanced: Guarda la hora de inicio, nombre de la sesión y del grupo del experimento y comienza el experimento.
• Carga: 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 Labvanced: Guarda la información meta en el servidor.
• Carga: JSON con los siguientes campos:

3.5 Registrar información sobre una tarea

• Ruta: /recordStartTask
• Tipo: POST
• Llamado cuando: Una nueva tarea comienza en el flujo experimental.
• Función en el servidor de Labvanced: No se llama cuando se activan solicitudes de API externas.
• Carga: JSON con los siguientes campos:

3.6 Registrar datos de prueba

• Ruta: /recordTrial
• Tipo: POST
• Llamado cuando: Una prueba finaliza O se ejecuta una acción de registro personalizada.
• Función en el servidor de Labvanced: No se llama cuando se activan solicitudes de API externas.
• Carga: JSON con los siguientes campos:

NOTA: Los datos exactos que se registran por prueba dependen del experimento y la tarea específicos. Un resumen para cada estudio está disponible en la pestaña "Variables" del experimento específico (ver captura de pantalla). También tenga en cuenta que los nombres de las variables de API externas se utilizarán como una 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 Labvanced generalmente obliga al usuario a utilizar nombres de variables únicos.

3.7 Finalizar el experimento con éxito

• Ruta: /finishExpSession
• Tipo: POST
• Llamado cuando: El experimento se finaliza con éxito.
• Función en el servidor de Labvanced: Finaliza el estudio y marca el conjunto de datos como completo (importante para el balanceo).
• Carga: JSON con los siguientes campos:

3.8 Finalizar el experimento con fallo

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

3.9 Cargar 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 Labvanced: No se llama cuando se activan 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: JSON con los siguientes campos:

Respuesta Requerida: