Webhook API
Usage : Le principal cas d'utilisation de l'API Webhook de stockage de données externes de 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 de 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 de Labvanced (une telle fonctionnalité n'existe pas pour l'instant), mais plutôt comment vous devez configurer/implémenter votre backend, de manière à ce que notre plateforme puisse automatiquement appeler les points de terminaison que vous avez implémentés 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 licences Labvanced Lab.
1. Configuration de l'API Webhook
Pour utiliser l'API Webhook, il faut d'abord activer l'option "stockage de données externes" dans "Paramètres de l'étude" de l'étude Labvanced respective sous la section "Fonctionnalités de l'expérience".
1.1 Paramètres :
- Adresse IP : Entrez votre adresse IP statique où votre serveur externe est en cours d'exécution / publiquement disponible.
- Port : Le port à utiliser pour envoyer les données
- Chemin URL : Le chemin URL qui doit être ajouté après le port. Cela est particulièrement utile pour "noms de domaine" de vos projets / données entrantes, de manière à ce que les données de différentes expériences soient envoyées à un chemin URL différent. Le chemin URL est optionnel, mais nous recommandons fortement de l'utiliser.
2. Créer le serveur / script pour recevoir les données de l'API Webhook
En fonction de vos paramètres à l'étape 1, vous devez mettre en œuvre un serveur qui est disponible à l'adresse IP, au port et au chemin URL spécifiés. Une version simplifiée / un exemple de tel serveur est disponible sur notre page Github ici.
2.1 Format des données : Les 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 des fichiers audio enregistrés) est codée en tant que “multipart/form-data”, donc veuillez vous assurer que vous analysez les données entrantes correctement en tant que JSON ou multipart/form-data / données binaires.
2.2. Paramètres CORS : Lors de la mise en œuvre de votre backend, vous devez implémenter / autoriser le partage de 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 est uniquement requise 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 prend part à une étude, un total de 8 types différents 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, audio ou 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/payload différente, qui doit être prise 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 / routes de l'API Webhook :
Dans ce qui suit, vous verrez une explication détaillée de chaque route / point de terminaison qui est utilisé/appelé lorsqu'un participant prend part à l'expérience. Idéalement, nous vous suggérons d'implémenter tous ces points de terminaison (sauf le 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 / le 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 l'équilibre des groupes et le flux général de l'expérience) et au serveur externe/votre.
- Les points de terminaison 3.5 et 3.6 sont uniquement envoyés au serveur externe/votre. Veuillez noter que toutes les données des essais/participants sont envoyées via la route 3.6, qui est donc le point de terminaison le plus important à implémenter.
- Le point de terminaison 3.9 est uniquement envoyé au serveur externe/votre et est 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é lorsque : Le participant visite une certaine URL d'expérience sur labvanced.com Fonction principale sur le serveur Labvanced : Initialise le chargement de l'expérience.
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
isTestrun | Si les données sont enregistrées ou non | Boolean | NON |
subject_code | Identifiant du sujet via le paramètre URL | Chaine de caractères | NON |
token | Un identifiant unique pour les participants dans les études longitudinales | Identifiant de jeton | NON |
askSubjData | Si une enquête initiale doit être affichée, utilisée pour placer les sujets dans différents groupes | Boolean | OUI |
NOTE : Ne doit pas être implémenté sur les serveurs externes, car cela initialise uniquement le chargement de l'expérience depuis le serveur Labvanced vers l'ordinateur client
3.2 Sélection du groupe et de la session
- Route : /startFirstPlayerSession
- Type : POST
- Appelé lorsque : Le point de terminaison 3.1 “/startExpPlayer” renvoie avec succès depuis le serveur Labvanced.
- Fonction principale sur le serveur Labvanced : Utilisé pour assigner des numéros de groupe et de session à un sujet (équilibrage côté serveur)
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
subject_code | Identifiant du sujet via le paramètre URL | Chaine de caractères | NON |
token | Un identifiant unique pour les participants dans les études longitudinales | Identifiant de jeton | NON |
survey_data | JSON du questionnaire pré-étude, champs décrits ci-dessous. | JSON | NON |
survey_data.selectedGender | Genre sélectionné du participant | Chaine de caractères | NON |
survey_data.selectedAge | Âge sélectionné du participant | Entier | NON |
survey_data.selectedCountry | Pays/localisation sélectionné du participant | Chaine de caractères | NON |
survey_data.selectedLanguage | Langue (première) sélectionnée du participant | Chaine de caractères | NON |
isTestrun | Si les données sont enregistrées ou non | Boolean | OUI |
runOnlyGroupNr | Utilisé uniquement pour tester un certain numéro de groupe sans enregistrements de données | Entier / Faux | NON |
runOnlySessionNr | Utilisé uniquement pour tester un certain numéro de session sans enregistrements de données | Entier / Faux | NON |
groupNr | Numéro de groupe pour ce sujet | Entier | OUI |
sessionNr | Numéro de session dans une étude longitudinale | Entier | OUI |
group_name | Nom du groupe pour ce sujet | Chaine de caractères | OUI |
session_name | Nom de la session pour ce sujet | Chaine de caractères | OUI |
experiment_name | Nom de l'expérience (pas le nom de publication) | Chaine de caractères | OUI |
3.3 Début de l'expérience
- Route : /setPlayerSessionStartedTime
- Type : POST
- Appelé lorsque : Le participant appuie sur “Démarrer l'expérience”
- Fonction sur le serveur Labvanced : Sauvegarde l'heure de début, la session et le nom du groupe de l'expérience et démarre l'expérience.
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
start_time | Heure de début de l'expérience | Horodatage UNIX | OUI |
sessionNr | Numéro de session dans une étude longitudinale | Entier | OUI |
groupNr | Numéro de groupe pour ce sujet | Entier | OUI |
token | Un identifiant unique pour les participants dans les études longitudinales | Identifiant de jeton | NON |
3.4 Ajouter des informations de métadonnées
- Route : /addMetaInfo
- Type : POST
- Appelé lorsque : Le participant appuie sur “Démarrer l'expérience”
- Fonction sur le serveur Labvanced : Sauvegarde les informations de métadonnées sur le serveur.
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
var_data | Le JSON contenant les informations de métadonnées | JSON | OUI |
var_data.browserSpec | Le navigateur utilisé par le sujet | Chaine de caractères | NON |
var_data.versionSpec | La version du navigateur utilisée par le sujet | Chaine de caractères | NON |
var_data.systemSpec | Le type de dispositif / OS utilisé par le sujet | Chaine de caractères | NON |
var_data.agentSpec | La chaîne complète de l'agent utilisateur | Chaine de caractères | NON |
var_data.fullscreen | Indique si l'étude est toujours en plein écran | Boolean | NON |
var_data.timeDelayMean | La précision du rappel JavaScript moyenne par offset en millisecondes | Flottant | NON |
var_data.timeDelayStd | L'écart type de la précision du rappel JavaScript en millisecondes | Flottant | NON |
var_data.crowdsourcingCode | Le code de crowdsourcing / de complétion pour les sujets | Chaine de caractères | NON |
var_data.crowdsourcinSubjId | L'identifiant de crowdsourcing / travailleur du sujet | Chaine de caractères | NON |
var_data.subjCounterGlobal | Un compteur global de sujets pour le nombre de sujets dans l'étude | Entier | NON |
var_data.subjCounterPer Group | Un compteur de sujets par groupe dans l'étude | Tableau d'entiers | NON |
var_data.roleId | L'identifiant de rôle unique pour les études multi-utilisateurs du sujet | Entier | NON |
var_data.multiUserGroupId | L'identifiant de groupe multi-utilisateur unique à l'échelle mondiale pour les études multi-utilisateurs | Uuid | NON |
var_data.displayedLanguage | La langue d'affichage sélectionnée pour les études multilingues | Chaine de caractères | NON |
var_data.pixelDensityPerMM | La densité de pixels de l'écran | Flottant | NON |
var_data.screenHeight | La hauteur de l'écran en pixels | Entier | NON |
var_data.screenWidth | La largeur de l'écran en pixels | Entier | NON |
var_data.windowHeight | La hauteur de la fenêtre / viewport en pixels | Entier | NON |
var_data.windowWidth | La largeur de la fenêtre/viewport en pixels | Entier | NON |
3.5 Enregistrer des informations sur une tâche
- Route : /recordStartTask
- Type : POST
- Appelé lorsque : Une nouvelle tâche démarre dans le flux de l'expérience
- Fonction sur le serveur Labvanced : Non appelé lorsque des requêtes API externes sont activées
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
blockNr | Numéro du bloc actuel (compteur croissant) | Entier | OUI |
blockId | Identifiant unique du bloc actuel | Uuid | OUI |
blockName | Nom du bloc | Chaine de caractères | OUI |
taskNr | Numéro de tâche actuel (compteur croissant) | Entier | OUI |
taskId | ID de la tâche actuelle tel que défini dans l'éditeur (identique entre les sujets) | Uuid | OUI |
recTaskId | ID généré par le serveur pour la tâche d'enregistrement actuelle (différent entre les sujets) | Entier | OUI |
taskName | Nom de la tâche actuelle | Chaine de caractères | OUI |
start_time | Heure de début de la tâche | Horodatage UNIX | OUI |
3.6 Enregistrer les données d'essai
- Route : /recordTrial
- Type : POST
- Appelé lorsque : Un essai est terminé OU une action d'enregistrement personnalisée est exécutée
- Fonction sur le serveur Labvanced : Non appelé lorsque des requêtes API externes sont activées.
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
recTaskId | ID généré par le serveur pour la tâche d'enregistrement actuelle (différent entre les sujets) | Entier | OUI |
taskId | ID de la tâche actuelle tel que défini dans l'éditeur (identique entre les sujets) | Uuid | OUI |
trailNr | Numéro de l'essai | Entier | OUI |
recData | Les données principales / toutes les variables créées par l'utilisateur par essai sont stockées ici | JSON | OUI |
NOTE : 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. Assurez-vous donc 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 Finir l'expérience avec succès
- Route : /finishExpSession
- Type : POST
- Appelé lorsque : L'expérience est terminée avec succès
- Fonction sur le serveur Labvanced : Termine l'étude et marque l'ensemble de données comme complété (important pour l'équilibrage).
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
end_time | Heure à laquelle l'expérience s'est terminée | Horodatage UNIX | OUI |
var_data | Identique aux données var dans la route “/addMetaInfo” (informations mises à jour) | JSON | OUI |
nextStartTime | Prochaine heure de début (uniquement pour les études longitudinales) | Horodatage UNIX | NON |
nextEndTime | Prochaine heure de fin (uniquement pour les études longitudinales) | Horodatage UNIX | NON |
reminderTime | Heure jusqu'à la prochaine heure de début (uniquement pour les études longitudinales) | Chaîne de temps | NON |
selectedEmail | Email pour envoyer un rappel de participation (uniquement pour les études longitudinales) | Adresse électronique | NON |
emailReminder | Quand envoyer le rappel (uniquement pour les études longitudinales) | Chaîne | NON |
3.8 Finir l'expérience avec échec
- Route : /errExpSession
- Type : POST
- Appelé lorsque : L'expérience est abandonnée avec une erreur
- Fonction sur le serveur Labvanced : Abandonne l'étude et marque l'ensemble de données comme incomplet
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expId | Identifiant unique pour l'étude | Entier | OUI |
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
err_msg | Le message d'erreur | Chaine de caractères | OUI |
3.9 Téléverser des données binaires (audio ou vidéo)
- Route : /file_upload
- Type : POST
- Appelé lorsque : Une action de téléversement est exécutée dans le système d'événements associée à un objet d'enregistrement audio ou vidéo. Fonction sur le serveur Labvanced : Non appelé lorsque des requêtes API externes sont activées.
- NOTE : Le serveur doit envoyer des valeurs de retour pour cette route (expliqué 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 également noter que les données dans cette route sont codées en tant que “multipart/form-data” car elles incluent à la fois des données binaires et non binaires.
- Payload : JSON avec les champs suivants :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
expSessionNr | Identifiant unique pour la session d'enregistrement pour ce participant (en croissance) | Chaine de caractères | OUI |
newFileName | Le nom de fichier suggéré pour stocker le fichier. Le nom de fichier comprend le nom de variable associé, et le numéro actuel du bloc, de la tâche et de l'essai. | Chaine de caractères | OUI |
myFile | Le fichier réel / les données binaires | Binaire | OUI |
Réponse requise :
Nom du champ | Description | Type de données | Requis |
---|---|---|---|
file_guid | Identifiant Unique Global (guid) pour le fichier enregistré. Cela doit être généré côté serveur et sera sauvegardé dans la variable associée au fichier de manière à ce qu'il soit facile de comprendre plus tard quel fichier provient de quel objet d'enregistrement. | Uuid | OUI |
file_name | Le nom de fichier résultant que le serveur a utilisé pour sauvegarder le fichier. Cela peut être (mais ne doit pas forcément être) le même nom de fichier suggéré par le client dans la requête. Cela sera également stocké dans la variable associée. | Chaine de caractères | OUI |