Webhook-API

Verwendung: ​Der Hauptanwendungsfall für die Labvanced Webhook-API zur externen Datenspeicherung besteht darin, Teilnehmerdaten in “Echtzeit” an einen externen / entfernten Server zu übertragen, anstatt die aufgezeichneten Daten auf den Labvanced-Servern zu hosten.

BITTE BEACHTEN: ​Im Gegensatz zu vielen API-Anwendungsszenarien beschreibt dieser Abschnitt NICHT, wie man die Labvanced-API / Endpunkte aufruft (eine solche Funktionalität existiert derzeit nicht), sondern wie Sie Ihr Backend konfigurieren/implementieren müssen, sodass unsere Plattform automatisch die Endpunkte aufruft, die Sie implementiert haben, um die Teilnehmerdaten direkt an Ihr Backend/Datenbank anstelle unseres 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 nutzen, muss zunächst die Option “externer Datenspeicher” in den “Studieneinstellungen” der jeweiligen Labvanced-Studie im Abschnitt “Experimentfeatures” aktiviert werden.

1.1 Parameter:

• IP-Adresse: Geben Sie Ihre statische IP-Adresse an, 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 angehängt werden soll. Dies ist besonders nützlich, um Ihre Projekte / eingehenden Daten zu “namensbereichen”, sodass 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 Sie den Server / das Skript zum Empfang 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 / ein Beispiel eines solchen Servers ist auf unserer Github-Seite hier verfügbar.

2.1 Datenformat: D​aten werden im 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 Audio verwendet wird) ist als “multipart/form-data” kodiert, stellen Sie daher 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 verwendet werden, um Daten zu senden. 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 ​Typen​ von POST-Anfragen an den (externen/Ihren) Server gesendet. Die Route “/file_upload” wird nur verwendet, wenn Ihre Studie eine Aktion zum Hochladen einiger aufgezeichneter Binärdaten (z. B. Audio oder Video) enthält. Jeder Typ von POST-Anfrage hat eine andere Route (URL-Pfad), die an den angegebenen URL-Pfad in Schritt 1 angehängt wird. Auch jeder Typ von Anfrage hat eine andere Struktur / Payload, die bei der Analyse und Speicherung der Daten berücksichtigt werden sollte. Einzelheiten finden Sie im Abschnitt 3.

3. Definitionen / Routen der Webhook-API-Endpunkte:

Im Folgenden finden Sie eine detaillierte Erklärung jeder Route / jedes Endpunkts, der verwendet / aufgerufen wird, wenn ein Teilnehmer am Experiment teilnimmt. Idealerweise empfehlen wir, dass Sie all 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?

• Der Endpunkt 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 (benötigt für die Gruppenbalancierung 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 Versuchs- / Teilnehmerdaten ü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 bei jeder Ausführung einer “Upload-Aktion” aufgerufen, um binäre (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 Lavanced-Server: Initialisiert das Laden des Experiments.
• Payload: JSON mit den folgenden Feldern:

HINWEIS: Muss nicht auf externen Servern implementiert werden, da dies nur das Laden des Experiments vom Labvanced-Server zum Client-Computer initialisiert

3.2 Gruppen- und Sitzungswahl

• Route: /startFirstPlayerSession
• Typ: POST
• Aufgerufen wenn: Route 3.1 “ /startExpPlayer” vom Labvanced-Server erfolgreich zurückgegeben wird.
• Hauptfunktion auf dem Labvanced-Server: Wird verwendet, um Gruppen- und Sitzungsnummern einem Subjekt zuzuweisen (serverseitiges Balancing).
• Payload: JSON mit den folgenden Feldern:

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.
• Payload: JSON mit den folgenden Feldern:

3.4 Fügen Sie Metadateninformationen hinzu

• Route: /addMetaInfo
• Typ: POST
• Aufgerufen wenn: Der Teilnehmer auf “Experiment starten” drückt.
• Funktion auf dem Labvanced-Server: Speichert die Metainformationen auf dem Server.
• Payload: JSON mit den folgenden Feldern:

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.
• Payload: JSON mit den folgenden Feldern:

3.6 Trialdaten 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.
• Payload: JSON mit den folgenden Feldern:

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 unter dem Tab "Variablen" des spezifischen Experiments (siehe Screenshot). Bitte beachten Sie auch, dass die externen API-Variablennamen als Schlüssel in der JSON-Struktur verwendet werden. Stellen Sie daher sicher, dass die Variablennamen eindeutig sind. Andernfalls würden Sie die Daten überschreiben. Das Labvanced-System zwingt in der Regel den Benutzer dazu, eindeutige Variablennamen zu verwenden.

3.7 Experiment erfolgreich beenden

• Route: /finishExpSession
• Typ: POST
• Aufgerufen wenn: Das Experiment erfolgreich abgeschlossen ist.
• Funktion auf dem Labvanced-Server: Beendet die Studie und markiert den Datensatz als abgeschlossen (wichtig für das Balancing).
• Payload: JSON mit den folgenden Feldern:

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 markiert den Datensatz als unvollständig.
• Payload: JSON mit den folgenden Feldern:

3.9 Hochladen von Binär- (Audio- oder Video-)Daten

• Route: /file_upload
• Typ: POST
• Aufgerufen wenn: Eine Upload-Aktion im Ereignissystem ausgeführt wird, die mit einem Audio- oder Videoaufzeichnungsobjekt verbunden ist. 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 (siehe unten). Wenn dies nicht erfolgt, wird der “onUploadComplete”-Trigger nicht ausgeführt und das Experiment kann sich nicht korrekt propagieren. 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.
• Payload: JSON mit den folgenden Feldern:

Erforderliche Antwort: