Webhook-API
Verwendung: Der Hauptverwendungszweck der Labvanced External Data Storage Webhook-API besteht darin, Teilnehmerdaten in „Echtzeit“ an einen externen/fernen Server zu übertragen, anstatt die aufgezeichneten Daten auf den Labvanced-Servern zu hosten.
BITTE BEACHTEN: Im Gegensatz zu vielen API-Anwendungsfällen beschreibt dieser Abschnitt NICHT, wie die Labvanced-API/Endpoints aufgerufen werden (eine solche Funktionalität existiert derzeit nicht), sondern wie Sie Ihr Backend konfigurieren/implementieren müssen, damit unsere Plattform in der Lage ist, die Endpoints, die Sie implementiert haben, automatisch aufzurufen, um die Teilnehmerdaten direkt an Ihr Backend/Ihre Datenbank anstelle von unserer zu senden.
Verfügbarkeit: Diese Funktionalität ist nur für Inhaber einer Labvanced-Lizenz verfügbar.
1. Einrichtung der Webhook-API
Um die Webhook-API zu verwenden, muss zuerst die Option „externe Datenspeicherung“ in den „Studieneinstellungen“ der jeweiligen Labvanced-Studie im Abschnitt „Experiment-Features“ aktiviert werden.
1.1 Parameter:
- IP-Adresse: Enter Ihre statische IP-Adresse, unter der Ihr externer Server läuft / öffentlich verfügbar ist.
- Port: Der Port, der zum Senden der Daten verwendet werden soll
- URL-Pfad: Der URL-Pfad, der nach dem Port hinzugefügt werden soll. Dies ist besonders nützlich, um Ihre Projekte/eingehenden Daten „namensraum“ zuzuordnen, sodass die Daten aus verschiedenen Experimenten an einen anderen URL-Pfad gesendet werden. Der URL-Pfad ist optional, aber wir empfehlen dringend, ihn zu verwenden.
2. Erstellen des Servers / Scripts zum Empfangen der Daten von der Webhook-API
Basierend auf Ihren Einstellungen in Schritt 1 müssen Sie einen Server implementieren, der unter der angegebenen IP-Adresse, dem Port und dem URL-Pfad verfügbar ist. Eine vereinfachte Version / Beispiel eines solchen Servers finden Sie auf unserer Github-Seite hier.
2.1 Datenformat: Daten werden in JSON-Format für alle Routen außer der Route „/file_upload“ gesendet. Die Route „/file_upload“ (die zum Hochladen von Binärdateien wie aufgezeichneten Videos oder Audios verwendet wird) ist als „multipart/form-data“ codiert, daher stellen Sie bitte sicher, dass Sie die eingehenden Daten korrekt als JSON oder multipart/form-data / Binärdaten analysieren.
2.2. CORS-Einstellungen: Bei der Implementierung Ihres Backends müssen Sie Cross Origin Resource Sharing (CORS) implementieren / zulassen. Insbesondere müssen Sie die folgenden Header festlegen: „Access-Control-Allow-Origin“ (einschließlich https://www.labvanced.com/), „Access-Control-Allow-Methods“ (einschließlich POST und OPTIONS), „Access-Control-Allow-Headers“ (einschließlich Content-Type)
2.3 Anfragearten: Alle Anfragearten sind POST-Anfragen, da sie zum Senden von Daten verwendet werden. An diesem Punkt ist ein Rückgabewert nur für die Route „/file_upload“ erforderlich. Alle anderen Routen benötigen keinen speziellen Rückgabewert.
2.4 Arten von Anfragen / Routen: Jedes Mal, wenn ein Teilnehmer an einer Studie teilnimmt, werden insgesamt 8 verschiedene Arten von POST-Anfragen an den (externen / Ihren) Server gesendet. Die Route „/file_upload“ wird nur verwendet, wenn Ihre Studie eine Aktion zum Hochladen von aufgezeichneten Binärdaten (z. B. Audio oder Video) beinhaltet. Jede Art von POST-Anfrage hat eine andere Route (URL-Pfad), die an den im Schritt 1 angegebenen URL-Pfad angehängt wird. Außerdem hat jede Anfrage eine andere Struktur/Nutzlast, die bei der Analyse und Speicherung der Daten berücksichtigt werden sollte. Siehe Details in Abschnitt 3.
3. Definitionen der Webhook-API-Endpunkte / Routen:
Im Folgenden finden Sie eine detaillierte Erklärung jeder Route / jedes Endpunkts, die verwendet/aufgerufen wird, wenn ein Teilnehmer am Experiment teilnimmt. Idealerweise empfehlen wir, dass Sie alle diese Endpunkte (außer 3.1) implementieren und sicherstellen, dass alle Daten angemessen analysiert und in Ihrer Datenbank gespeichert werden.
Welche Endpunkte werden verwendet, welcher Server wird wann aufgerufen?
- Endpoint 3.1 „/startExpPlayer“ wird nur an den Labvanced-Server gesendet, um die Experimentdefinition/JSON-Datei und die zugehörigen Stimuli von unserem Server zu laden.
- Die Endpunkte 3.2, 3.3, 3.4, 3.7 und 3.8 werden sowohl an den Labvanced-Server (notwendig für die Gruppenbalance und den allgemeinen Experimentablauf) als auch an den externen/ Ihren Server gesendet.
- Die Endpunkte 3.5 und 3.6 werden nur an den externen/Ihren Server gesendet. Bitte beachten Sie, dass alle Daten der Trials/Teilnehmer über die Route 3.6 gesendet werden, die daher der wichtigste Endpunkt zum Implementieren ist.
- Der Endpunkt 3.9 wird nur an den externen/ Ihren Server gesendet und jedes Mal aufgerufen, wenn eine „Upload-Aktion“ ausgeführt wird, um Binär- (Audio- oder Video-)Daten hochzuladen.
3.1 Laden des Experiments
- Route: /startExpPlayer
- Typ: POST
- Aufgerufen, wenn: Der Teilnehmer eine bestimmte Experiment-URL auf labvanced.com besucht. Hauptfunktion auf dem Labvanced-Server: Initialisiert das Laden des Experiments.
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
isTestrun | Ob die Daten aufgezeichnet oder nicht | Boolean | NEIN |
subject_code | Identifier des Teilnehmers über den URL-Parameter | Zeichenfolge | NEIN |
token | Ein eindeutiger Identifikator für Teilnehmer in longitudinalen Studien | Token-Identifikator | NEIN |
askSubjData | Ob eine anfängliche Umfrage angezeigt werden soll, die verwendet wird, um Probanden in verschiedene Gruppen einzuteilen | Boolean | JA |
HINWEIS: Muss nicht auf externen Servern implementiert werden, da dies nur das Laden des Experiments vom Labvanced-Server auf den Client-Computer initialisiert
3.2 Gruppen- und Sitzungszuweisung
- Route: /startFirstPlayerSession
- Typ: POST
- Aufgerufen, wenn: Route 3.1 „ /startExpPlayer“ erfolgreich vom Labvanced-Server zurückgegeben wird.
- Hauptfunktion auf dem Labvanced-Server: Wird verwendet, um Gruppen- und Sitzungsnummern einem Teilnehmer zuzuweisen (Server-seitige Balance)
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
subject_code | Identifier des Teilnehmers über den URL-Parameter | Zeichenfolge | NEIN |
token | Ein eindeutiger Identifikator für Teilnehmer in longitudinalen Studien | Token-Identifikator | NEIN |
survey_data | JSON des vorstudien Fragebogens, die nachfolgend beschriebenen Felder. | JSON | NEIN |
survey_data.selectedGender | Ausgewähltes Geschlecht des Teilnehmers | Zeichenfolge | NEIN |
survey_data.selectedAge | Ausgewähltes Alter des Teilnehmers | Ganzzahl | NEIN |
survey_data.selectedCountry | Ausgewähltes Land/Standort des Teilnehmers | Zeichenfolge | NEIN |
survey_data.selectedLanguage | Ausgewählte (erste) Sprache des Teilnehmers | Zeichenfolge | NEIN |
isTestrun | Ob die Daten aufgezeichnet werden oder nicht | Boolean | JA |
runOnlyGroupNr | Wird nur verwendet, um eine bestimmte Gruppennummer ohne Datenaufzeichnungen zu testen | Ganzzahl / Falsch | NEIN |
runOnlySessionNr | Wird nur verwendet, um eine bestimmte Sitzungsnummer ohne Datenaufzeichnungen zu testen | Ganzzahl / Falsch | NEIN |
groupNr | Gruppennummer für diesen Teilnehmer | Ganzzahl | JA |
sessionNr | Sitzungsnummer in einer longitudinalen Studie | Ganzzahl | JA |
group_name | Der Name der Gruppe für diesen Teilnehmer | Zeichenfolge | JA |
session_name | Der Name der Sitzung für diesen Teilnehmer | Zeichenfolge | JA |
experiment_name | Der Experimentname (nicht der Veröffentlichungsname) | Zeichenfolge | JA |
3.3 Beginn des Experiments
- Route: /setPlayerSessionStartedTime
- Typ: POST
- Aufgerufen, wenn: Der Teilnehmer auf „Experiment starten“ drückt
- Funktion auf dem Labvanced-Server: Speichert die Startzeit, die Sitzung und den Gruppennamen des Experiments und startet das Experiment.
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
start_time | Startzeit des Experiments | UNIX-Zeitstempel | JA |
sessionNr | Sitzungsnummer in einer longitudinalen Studie | Ganzzahl | JA |
groupNr | Gruppennummer für diesen Teilnehmer | Ganzzahl | JA |
token | Ein eindeutiger Identifikator für Teilnehmer in longitudinalen Studien | Token-Identifikator | NEIN |
3.4 Hinzufügen von Metadaten
- Route: /addMetaInfo
- Typ: POST
- Aufgerufen, wenn: Der Teilnehmer auf „Experiment starten“ drückt
- Funktion auf dem Labvanced-Server: Speichert die Metainformationen auf dem Server.
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
var_data | Das JSON, das die Metainformationen enthält | JSON | JA |
var_data.browserSpec | Der Browser, der vom Teilnehmer verwendet wird | Zeichenfolge | NEIN |
var_data.versionSpec | Die Browser-Version, die vom Teilnehmer verwendet wird | Zeichenfolge | NEIN |
var_data.systemSpec | Der Gerätetyp / das Betriebssystem, das vom Teilnehmer verwendet wird | Zeichenfolge | NEIN |
var_data.agentSpec | Die vollständige Benutzeragentenzeichenfolge | Zeichenfolge | NEIN |
var_data.fullscreen | Gibt an, ob die Studie immer im Vollbildmodus ist | Boolean | NEIN |
var_data.timeDelayMean | Der mittelwert der JavaScript-Rückruffrequenz in Millisekunden | Float | NEIN |
var_data.timeDelayStd | Die Standardabweichung der JavaScript-Rückruffrequenz in Millisekunden | Float | NEIN |
var_data.crowdsourcingCode | Der Crowdsourcing-/Abschlusscode für Teilnehmer | Zeichenfolge | NEIN |
var_data.crowdsourcinSubjId | Die Crowdsourcing-/Arbeiter-ID des Teilnehmers | Zeichenfolge | NEIN |
var_data.subjCounterGlobal | Ein globaler Zähler für die Anzahl der Teilnehmer in der Studie | Ganzzahl | NEIN |
var_data.subjCounterPer Group | Ein Zähler für die Teilnehmer pro Gruppe in der Studie | Array von ganzzahlen | NEIN |
var_data.roleId | Die eindeutige Rollen-ID für Mehrbenutzerstudien des Teilnehmers | Ganzzahl | NEIN |
var_data.multiUserGroupId | Die global eindeutige Mehrbenutzergruppen-ID für Mehrbenutzerstudien | Uuid | NEIN |
var_data.displayedLanguage | Die ausgewählte Anzeigesprache für mehrsprachige Studien | Zeichenfolge | NEIN |
var_data.pixelDensityPerMM | Die Pixeldichte des Bildschirms | Float | NEIN |
var_data.screenHeight | Die Höhe des Bildschirms in Pixeln | Ganzzahl | NEIN |
var_data.screenWidth | Die Breite des Bildschirms in Pixeln | Ganzzahl | NEIN |
var_data.windowHeight | Die Fenster-/Viewport-Höhe in Pixeln | Ganzzahl | NEIN |
var_data.windowWidth | Die Fenster-/Viewport-Breite in Pixeln | Ganzzahl | NEIN |
3.5 Informationen über eine Aufgabe aufzeichnen
- Route: /recordStartTask
- Typ: POST
- Aufgerufen, wenn: Eine neue Aufgabe im Experimentablauf beginnt
- Funktion auf dem Labvanced-Server: Wird nicht aufgerufen, wenn externe API-Anfragen aktiviert sind
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
blockNr | Aktuelle Blocknummer (steigender Zähler) | Ganzzahl | JA |
blockId | Eindeutige ID des aktuellen Blocks | Uuid | JA |
blockName | Name des Blocks | Zeichenfolge | JA |
taskNr | Aktuelle Aufgabennummer (steigender Zähler) | Ganzzahl | JA |
taskId | ID der aktuellen Aufgabe, wie im Editor definiert (gleich zwischen Teilnehmern) | Uuid | JA |
recTaskId | Vom Server generierte ID für die aktuelle Aufzeichnungsaufgabe (unterschiedlich zwischen Teilnehmern) | Ganzzahl | JA |
taskName | Name der aktuellen Aufgabe | Zeichenfolge | JA |
start_time | Startzeit der Aufgabe | UNIX-Zeitstempel | JA |
3.6 Trial-Daten aufzeichnen
- Route: /recordTrial
- Typ: POST
- Aufgerufen, wenn: Ein Versuch abgeschlossen ist ODER eine benutzerdefinierte Aufzeichnungsaktion ausgeführt wird
- Funktion auf dem Labvanced-Server: Wird nicht aufgerufen, wenn externe API-Anfragen aktiviert sind.
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
recTaskId | Vom Server generierte ID für die aktuelle Aufzeichnungsaufgabe (unterschiedlich zwischen Teilnehmern) | Ganzzahl | JA |
taskId | ID der aktuellen Aufgabe, wie im Editor definiert (gleich zwischen Teilnehmern) | Uuid | JA |
trailNr | Versuchnummer | Ganzzahl | JA |
recData | Die Hauptdaten / alle vom Benutzer erstellten Variablen pro Versuch werden hier gespeichert | JSON | JA |
HINWEIS: Die genauen Daten, die pro Versuch aufgezeichnet werden, hängen vom spezifischen Experiment und der Aufgabe ab. Eine Übersicht für jede Studie finden Sie im Tab "Variablen" des jeweiligen Experiments (siehe Screenshot). Bitte beachten Sie auch, dass die Namen der externen API-Variablen als Schlüssel in der JSON-Struktur verwendet werden. Stellen Sie daher sicher, dass die Variablenamen eindeutig sind. Andernfalls würden Sie die Daten überschreiben. Das Labvanced-System zwingt den Benutzer normalerweise dazu, eindeutige Variablennamen zu verwenden.
3.7 Experiment erfolgreich beenden
- Route: /finishExpSession
- Typ: POST
- Aufgerufen, wenn: Das Experiment erfolgreich abgeschlossen wurde
- Funktion auf dem Labvanced-Server: Beendet die Studie und kennzeichnet den Datensatz als abgeschlossen (wichtig für die Balance).
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
end_time | Zeitpunkt, an dem das Experiment beendet wurde | UNIX-Zeitstempel | JA |
var_data | Dasselbe wie die Var-Daten in der Route „/addMetaInfo“ (aktualisierte Informationen) | JSON | JA |
nextStartTime | Nächste Startzeit (nur für longitudinale Studien) | UNIX-Zeitstempel | NEIN |
nextEndTime | Nächste Endzeit (nur für longitudinale Studien) | UNIX-Zeitstempel | NEIN |
reminderTime | Zeit bis zur nächsten Startzeit (nur für longitudinale Studien) | Zeitzeichenfolge | NEIN |
selectedEmail | E-Mail, um eine Erinnerung an die Teilnahme zu senden (nur für longitudinale Studien) | E-Mail-Adresse | NEIN |
emailReminder | Wann die Erinnerung gesendet werden soll (nur für longitudinale Studien) | Zeichenfolge | NEIN |
3.8 Experiment mit Fehler beenden
- Route: /errExpSession
- Typ: POST
- Aufgerufen, wenn: Das Experiment mit einem Fehler abgebrochen wird
- Funktion auf dem Labvanced-Server: Bricht die Studie ab und kennzeichnet den Datensatz als unvollständig
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expId | Eindeutiger Identifikator für die Studie | Ganzzahl | JA |
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
err_msg | Die Fehlermeldung | Zeichenfolge | JA |
3.9 Binäre (Audio- oder Video-)Daten hochladen
- Route: /file_upload
- Typ: POST
- Aufgerufen, wenn: Eine Upload-Aktion im Ereignissystem, die mit einem Audio- oder Videoaufnahmeobjekt verknüpft ist, ausgeführt wird. Funktion auf dem Labvanced-Server: Wird nicht aufgerufen, wenn externe API-Anfragen aktiviert sind.
- HINWEIS: Der Server muss Rückgabewerte für diese Route senden (nachfolgend erklärt). Wenn dies nicht geschieht, wird der „onUploadComplete“-Trigger nicht ausgeführt und das Experiment kann nicht korrekt propagiert werden. Bitte beachten Sie auch, dass die Daten in dieser Route als „multipart/form-data“ kodiert sind, da sie sowohl binäre als auch nicht-binäre Daten enthalten.
- Nutzlast: JSON mit den folgenden Feldern:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
expSessionNr | Eindeutiger Identifikator für die Aufzeichnungssitzung für diesen Teilnehmer (zählt nach oben) | Zeichenfolge | JA |
newFileName | Der empfohlene Dateiname zum Speichern der Datei. Der Dateiname enthält den zugehörigen Variablenamen sowie die aktuelle Block-, Aufgaben- und Versuchsnumer. | Zeichenfolge | JA |
myFile | Die tatsächliche Datei / Binärdaten | Binär | JA |
Erforderliche Antwort:
Feldname | Beschreibung | Datentyp | Erforderlich |
---|---|---|---|
file_guid | Globaler eindeutiger Identifikator (guid) für die aufgezeichnete Datei. Dieser muss serverseitig generiert und in der mit der Datei verknüpften Variablen gespeichert werden, sodass später leicht nachzuvollziehen ist, welche Datei von welchem Aufnahmeobjekt stammt. | Uuid | JA |
file_name | Der resultierende Dateiname, den der Server zum Speichern der Datei verwendet hat. Dies kann (muss aber nicht) der gleiche Dateiname sein, der vom Client in der Anfrage vorgeschlagen wurde. Dieser wird ebenfalls in der zugehörigen Variablen gespeichert. | Zeichenfolge | JA |