API Webhook

Utilisation : ​Le principal cas d'utilisation de l'API Webhook de stockage de données externes Labvanced est de transférer les données des participants en " temps réel " vers un serveur externe / distant, au lieu d'héberger les données enregistrées sur les serveurs Labvanced.

VEUILLEZ NOTER : ​Contrairement à de nombreux cas d'utilisation d'API, ce qui est décrit ici n'est PAS comment appeler l'API / les points de terminaison Labvanced (une telle fonctionnalité n'existe pas pour le moment), mais plutôt comment vous devez configurer/implémenter votre backend, de sorte que notre plateforme pourra automatiquement appeler les points de terminaison que vous avez mis en œuvre pour envoyer les données des participants directement à votre backend/base de données au lieu de la nôtre.

Disponibilité : ​Cette fonctionnalité n'est disponible que pour les titulaires de licence de laboratoire Labvanced.

1. Configuration de l'API Webhook

Pour utiliser l'API Webhook, il faut d'abord activer l'option "stockage de données externe" dans "Paramètres d'étude" de l'étude Labvanced respective sous la section "Fonctionnalités de l'expérience".

1.1 Paramètres :

• Adresse IP : S​aisissez votre adresse IP statique où votre serveur externe est opérationnel / accessible publiquement.
• Port : Le port qui doit être utilisé pour envoyer les données
• Chemin URL​ : Le chemin URL qui doit être ajouté après le port. Ceci est particulièrement utile pour "nombremétier" vos projets / données entrantes, de sorte que les données provenant de différentes expériences soient envoyées vers un chemin URL différent. Le chemin URL est facultatif, mais nous vous recommandons fortement de l'utiliser.

2. Créer le serveur / script pour recevoir les données de l'API Webhook

Basé sur vos paramètres dans l'étape 1, vous devez implémenter un serveur qui est disponible à l'adresse IP, au port et au chemin URL spécifiés. Une version simplifiée / exemple de ce type de serveur est disponible sur notre page Github ici.

2.1 Format de données : D​es données sont envoyées au format JSON pour toutes les routes sauf la route “/file_upload”. La route “/file_upload” (utilisée pour télécharger des fichiers binaires tels que des vidéos ou de l'audio enregistrés) est encodée en tant que “multipart/form-data”, donc veuillez vous assurer de parser les données entrantes correctement en tant que JSON ou multipart/form-data / données binaires.

2.2. Paramètres CORS : Lors de l'implémentation de votre backend, vous devez implémenter / autoriser le partage des ressources entre origines (CORS). En particulier, vous devez définir les en-têtes suivants : "Access-Control-Allow-Origin" (inclure ​https://www.labvanced.com/​), "Access-Control-Allow-Methods" (inclure POST et OPTIONS), "Access-Control-Allow-Headers" (inclure Content-Type)

2.3 Types de requêtes : ​Tous les types de requêtes sont des requêtes POST car elles sont utilisées pour envoyer des données. À ce stade, une valeur de retour n'est requise que pour la route “/file_upload”. Toutes les autres routes n'ont pas besoin d'une valeur de retour spéciale.

2.4 Types de requêtes / routes : ​Chaque fois qu'un participant participe à une étude, un total de 8 différents ​types​ de requêtes POST seront envoyés au serveur (externe /votre). La route “/file_upload” ne sera utilisée que si votre étude comprend une action pour télécharger des données binaires enregistrées (par exemple de l'audio ou de la vidéo). Chaque type de requête POST a une route (chemin URL) différente, qui sera ajoutée au chemin URL spécifié à l'étape 1. De plus, chaque type de requête a une structure/charge utile différente, ce qui doit être pris en compte lors de l'analyse et du stockage des données. Voir les détails dans la section 3.

3. Définitions des points de terminaison de l'API Webhook / Routes :

Dans ce qui suit, vous verrez une explication détaillée de chaque route / point de terminaison qui est utilisé/appelé lorsqu'un participant participe à l'expérience. Idéalement, nous vous suggérons d'implémenter tous ces points de terminaison (en dehors de 3.1), et de vous assurer que toutes les données sont correctement analysées et stockées dans votre base de données.

Quels points de terminaison sont utilisés, quel serveur est appelé quand ?

• Le point de terminaison 3.1 “/startExpPlayer” est uniquement envoyé au serveur Labvanced pour charger la définition de l'expérience/fichier JSON et les stimuli associés depuis notre serveur.
• Les points de terminaison 3.2, 3.3, 3.4, 3.7 et 3.8 sont envoyés à la fois au serveur Labvanced (nécessaire pour le balancement des groupes et le flux général de l'expérience) et au serveur externe/votre serveur.
• Les points de terminaison 3.5 et 3.6 ne sont envoyés qu'au serveur externe/votre serveur. Veuillez noter que toutes les données d'essai/participant sont envoyées via la route 3.6, qui est donc le point de terminaison le plus important à mettre en œuvre.
• Le point de terminaison 3.9 est uniquement envoyé au serveur externe/votre serveur et appelé chaque fois qu'une "action de téléchargement" est exécutée pour télécharger des données binaires (audio ou vidéo).

3.1 Chargement de l'expérience

• Route : /startExpPlayer
• Type : POST
• Appelé quand : Le participant visite une certaine URL d'expérience sur labvanced.com Fonction principale sur le serveur Lavanced : Initialise le chargement de l'expérience.
• Charge utile : JSON avec les champs suivants :

REMARQUE : N'a pas besoin d'être mis en œuvre sur les serveurs externes, car cela initialise uniquement le chargement de l'expérience à partir du serveur Labvanced vers l'ordinateur client

3.2 Sélection de groupe et de session

• Route : /startFirstPlayerSession
• Type : POST
• Appelé quand : La route 3.1 “ /startExpPlayer” retourne avec succès depuis le serveur Labvanced.
• Fonction principale sur le serveur Lavanced : Utilisée pour attribuer des numéros de groupe et de session à un sujet (équilibrage côté serveur)
• Charge utile : JSON avec les champs suivants :

3.3 Démarrage de l'expérience

• Route : /setPlayerSessionStartedTime
• Type : POST
• Appelé quand : Le participant appuie sur "Démarrer l'expérience"
• Fonction sur le serveur Lavanced : Enregistre l'heure de début, le nom de session et de groupe de l'expérience et démarre l'expérience.
• Charge utile : JSON avec les champs suivants :

3.4 Ajouter des informations metadata

• Route : /addMetaInfo
• Type : POST
• Appelé quand : Le participant appuie sur "Démarrer l'expérience"
• Fonction sur le serveur Lavanced : Enregistre les informations metadata sur le serveur.
• Charge utile : JSON avec les champs suivants :

3.5 Enregistrer des informations sur une tâche

• Route : /recordStartTask
• Type : POST
• Appelé quand : Une nouvelle tâche commence dans le flux de l'expérience
• Fonction sur le serveur Lavanced : Non appelée lorsque des requêtes API externes sont activées
• Charge utile : JSON avec les champs suivants :

3.6 Enregistrer des données d'essai

• Route : /recordTrial
• Type : POST
• Appelé quand : Un essai est terminé OU une action d'enregistrement personnalisée est exécutée
• Fonction sur le serveur Lavanced : Non appelée lorsque des requêtes API externes sont activées.
• Charge utile : JSON avec les champs suivants :

REMARQUE : Les données exactes qui sont enregistrées par essai dépendent de l'expérience et de la tâche spécifiques. Un aperçu pour chaque étude est disponible sous l'onglet "Variables" de l'expérience spécifique (voir capture d'écran). Veuillez également noter que les noms de variables de l'API externe seront utilisés comme clé dans la structure JSON. Donc, veuillez vous assurer que les noms de variables sont uniques. Sinon, vous écraseriez les données. Le système Labvanced oblige généralement l'utilisateur à utiliser des noms de variables uniques.

3.7 Terminer l'expérience avec succès

• Route : /finishExpSession
• Type : POST
• Appelé quand : L'expérience est terminée avec succès
• Fonction sur le serveur Lavanced : Termine l'étude et marque le jeu de données comme complété (important pour l'équilibrage).
• Charge utile : JSON avec les champs suivants :

3.8 Terminer l'expérience avec une erreur

• Route : /errExpSession
• Type : POST
• Appelé quand : L'expérience est annulée avec une erreur
• Fonction sur le serveur Lavanced : Annule l'étude et marque le jeu de données comme incomplet
• Charge utile : JSON avec les champs suivants :

3.9 Télécharger des données binaires (audio ou vidéo)

• Route : /file_upload
• Type : POST
• Appelé quand : Une action de téléchargement est exécutée dans le système d'événements associé à un objet d'enregistrement audio ou vidéo. Fonction sur le serveur Lavanced : Non appelée lorsque des requêtes API externes sont activées.
• REMARQUE : Le serveur doit envoyer des valeurs de retour pour cette route (expliquées ci-dessous). Si cela n'est pas fait, le déclencheur “onUploadComplete” n'est pas exécuté et l'expérience ne peut pas se propager correctement. Veuillez noter également que les données dans cette route sont encodées en tant que “multipart/form-data” car elles incluent à la fois des données binaires et non binaires.
• Charge utile : JSON avec les champs suivants :

Réponse requise :