Webhook API
使用法: Labvancedの外部データストレージWebhook APIの主なユースケースは、記録されたデータをLabvancedのサーバー上にホストするのではなく、参加者データを“リアルタイム”で外部のリモートサーバーに転送することです。
注意: 多くのAPIユースケースとは異なり、ここで説明されているのはLabvanced API / エンドポイントを呼び出す方法ではなく（そのような機能は現在存在しません）、私たちのプラットフォームが、参加者データを私たちのバックエンド/データベースではなくあなたのバックエンド/データベースに直接送信するために、あなたが実装したエンドポイントを自動的に呼び出せるようにバックエンドを構成/実装する方法です。
利用可能性: この機能はLabvancedのラボライセンス所有者のみが利用できます。
1. Webhook APIの設定
Webhook APIを使用するには、最初にそれぞれのLabvanced研究の“実験機能”セクションの“研究設定”で“外部データストレージ”オプションを有効にする必要があります。
1.1 パラメータ:
- IPアドレス: 外部サーバーが稼働している/公に利用可能な静的IPアドレスを入力してください。
- ポート: データを送信するために使用するポート
- URLパス: ポートの後に追加すべきURLパスです。これは特に、異なる実験からのデータを異なるURLパスに送信するために、プロジェクト/受信データの“名前空間”を作成するのに便利です。URLパスはオプションですが、使用することを強く推奨します。
2. Webhook APIからデータを受信するためのサーバー/スクリプトの作成
ステップ1の設定に基づいて、指定されたIPアドレス、ポート、およびURLパスで利用可能なサーバーを実装する必要があります。このようなサーバーの簡略化されたバージョン/例は、私たちのGithubのページにあります。
2.1 データ形式: “/file_upload”ルートを除いて、すべてのルートでデータはJSON形式で送信されます。“/file_upload”ルート（記録されたビデオや音声などのバイナリファイルをアップロードするために使用される）は“multipart/form-data”としてエンコードされているため、受信データを正しくJSONまたはmultipart/form-data / バイナリデータとして解析することを確認してください。
2.2 CORS設定: バックエンドを実装する際には、Cross Origin Resource Sharing (CORS)を実装/許可する必要があります。特に、次のヘッダーを設定する必要があります：“Access-Control-Allow-Origin” (https://www.labvanced.com/を含む)、 “Access-Control-Allow-Methods”（POSTとOPTIONSを含む）、 “Access-Control-Allow-Headers”（Content-Typeを含む）
2.3 リクエストの種類: すべてのリクエストの種類はPOSTリクエストであり、データを送信するために使用されます。この時点では、“/file_upload”ルートにのみ戻り値が必要です。他のすべてのルートは特別な戻り値を必要としません。
2.4 リクエスト/ルートの種類: 参加者が研究に参加するたびに、合計で8種類の異なるPOSTリクエストが（外部/あなたの）サーバーに送信されます。“/file_upload”ルートは、あなたの研究に記録されたバイナリデータ（例：音声またはビデオ）をアップロードするアクションが含まれている場合にのみ使用されます。各タイプのPOSTリクエストには異なるルート（URLパス）があり、ステップ1で指定されたURLパスに追加されます。また、各リクエストの型には異なる構造/ペイロードがあり、データを解析および保存する際に考慮する必要があります。詳細はセクション3を参照してください。
3. Webhook APIエンドポイントの定義/ルート:
以下に、参加者が実験に参加する際に使用される/呼び出される各ルート/エンドポイントの詳細な説明を示します。理想的には、これらすべてのエンドポイント（3.1を除く）を実装し、すべてのデータが適切に解析され、データベースに保存されることを確認することをお勧めします。
どのエンドポイントが使用され、どのサーバーがいつ呼び出されますか？
- エンドポイント3.1 “/startExpPlayer”は、実験の定義/JSONファイルと関連する刺激を私たちのサーバーからロードするためにLabvancedサーバーにのみ送信されます。
- エンドポイント3.2、3.3、3.4、3.7、3.8は、グループバランスと一般的な実験フローに必要なLabvancedサーバーと外部/あなたのサーバーの両方に送信されます。
- エンドポイント3.5および3.6は、外部/あなたのサーバーにのみ送信されます。すべての試行/参加者データはルート3.6を介して送信されるため、これは実装するために最も重要なエンドポイントです。
- エンドポイント3.9は、外部/あなたのサーバーにのみ送信され、バイナリ（音声またはビデオ）データをアップロードするアクションが実行されるたびに呼び出されます。
3.1 実験の読み込み
- ルート: /startExpPlayer
- タイプ: POST
- 呼び出されるとき: 参加者がlabvanced.comの特定の実験URLを訪れるとき Labvancedサーバーの主要機能: 実験の読み込みを開始します。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| isTestrun | データが記録されるかどうか | ブール | いいえ |
| subject_code | URLパラメータ経由の対象者の識別子 | 文字列 | いいえ |
| token | 長期的な研究の参加者のためのユニークな識別子 | トークン識別子 | いいえ |
| askSubjData | 初期調査を表示するかどうか、対象者を異なるグループに分けるために使用されます | ブール | はい |
注意: これは外部サーバーで実装する必要はありません。これはLabvancedサーバーからクライアントコンピュータへの実験の読み込みを初期化するだけです。
3.2 グループとセッションの選択
- ルート: /startFirstPlayerSession
- タイプ: POST
- 呼び出されるとき: ルート3.1 “ /startExpPlayer”がLabvancedサーバーから正常に返されたとき。
- Labvancedサーバーの主要機能: 被験者にグループ番号とセッション番号を割り当てるために使用されます（サーバー側のバランス）。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| subject_code | URLパラメータ経由の対象者の識別子 | 文字列 | いいえ |
| token | 長期的な研究の参加者のためのユニークな識別子 | トークン識別子 | いいえ |
| survey_data | 事前研究アンケートのJSON、以下にフィールドを説明します。 | JSON | いいえ |
| survey_data.selectedGender | 参加者の選択された性別 | 文字列 | いいえ |
| survey_data.selectedAge | 参加者の選択された年齢 | 整数 | いいえ |
| survey_data.selectedCountry | 参加者の選択された国/場所 | 文字列 | いいえ |
| survey_data.selectedLanguage | 参加者の選択された（第一）言語 | 文字列 | いいえ |
| isTestrun | データが記録されるか否か | ブール | はい |
| runOnlyGroupNr | データ記録なしで特定のグループ番号をテスト実行するためにのみ使用 | 整数 / 偽 | いいえ |
| runOnlySessionNr | データ記録なしで特定のセッション番号をテスト実行するためにのみ使用 | 整数 / 偽 | いいえ |
| groupNr | この対象者のグループ番号 | 整数 | はい |
| sessionNr | 長期的な研究のセッション番号 | 整数 | はい |
| group_name | この対象者のグループ名 | 文字列 | はい |
| session_name | この対象者のセッション名 | 文字列 | はい |
| experiment_name | 実験名（出版名ではない） | 文字列 | はい |
3.3 実験の開始
- ルート: /setPlayerSessionStartedTime
- タイプ: POST
- 呼び出されるとき: 参加者が“実験を開始”を押したとき
- Labvancedサーバーの機能: 実験の開始時間、セッション名、およびグループ名を保存し、実験を開始します。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| start_time | 実験の開始時間 | UNIXタイムスタンプ | はい |
| sessionNr | 長期的な研究のセッション番号 | 整数 | はい |
| groupNr | この対象者のグループ番号 | 整数 | はい |
| token | 長期的な研究の参加者のためのユニークな識別子 | トークン識別子 | いいえ |
3.4 メタデータ情報の追加
- ルート: /addMetaInfo
- タイプ: POST
- 呼び出されるとき: 参加者が“実験を開始”を押したとき
- Labvancedサーバーの機能: サーバーにメタ情報を保存します。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| var_data | メタ情報を保持するJSON | JSON | はい |
| var_data.browserSpec | 対象者が使用しているブラウザ | 文字列 | いいえ |
| var_data.versionSpec | 対象者が使用しているブラウザのバージョン | 文字列 | いいえ |
| var_data.systemSpec | 対象者が使用しているデバイスタイプ / OS | 文字列 | いいえ |
| var_data.agentSpec | 完全なユーザーエージェント文字列 | 文字列 | いいえ |
| var_data.fullscreen | 研究が常に全画面であるかどうかを示す | ブール | いいえ |
| var_data.timeDelayMean | JavaScriptコールバック精度の平均オフセット（ミリ秒単位） | 浮動小数点 | いいえ |
| var_data.timeDelayStd | JavaScriptコールバック精度の標準偏差（ミリ秒単位） | 浮動小数点 | いいえ |
| var_data.crowdsourcingCode | 対象者のためのクラウドソーシング/完了コード | 文字列 | いいえ |
| var_data.crowdsourcinSubjId | 対象者のためのクラウドソーシング/ワーカーID | 文字列 | いいえ |
| var_data.subjCounterGlobal | 研究内の対象者のためのグローバルな対象者カウンター | 整数 | いいえ |
| var_data.subjCounterPer Group | 研究内のグループごとの対象者カウンター | 整数の配列 | いいえ |
| var_data.roleId | 対象者のためのマルチユーザ研究のユニークなロールID | 整数 | いいえ |
| var_data.multiUserGroupId | マルチユーザ研究のためのグローバルユニークなマルチユーザグループID | Uuid | いいえ |
| var_data.displayedLanguage | マルチランゲージ研究のための選択された表示言語 | 文字列 | いいえ |
| var_data.pixelDensityPerMM | スクリーンのピクセル密度 | 浮動小数点 | いいえ |
| var_data.screenHeight | スクリーンの高さ（ピクセル単位） | 整数 | いいえ |
| var_data.screenWidth | スクリーンの幅（ピクセル単位） | 整数 | いいえ |
| var_data.windowHeight | ウィンドウ/ビューポートの高さ（ピクセル単位） | 整数 | いいえ |
| var_data.windowWidth | ウィンドウ/ビューポートの幅（ピクセル単位） | 整数 | いいえ |
3.5 タスクに関する情報の記録
- ルート: /recordStartTask
- タイプ: POST
- 呼び出されるとき: 実験のフローで新しいタスクが開始されるとき
- Labvancedサーバーの機能: 外部APIリクエストが有効な場合は呼び出されません
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| blockNr | 現在のブロック番号（カウントアップ） | 整数 | はい |
| blockId | 現在のブロックのユニークID | Uuid | はい |
| blockName | ブロックの名前 | 文字列 | はい |
| taskNr | 現在のタスク番号（カウントアップ） | 整数 | はい |
| taskId | エディタで定義された現在のタスクのID（対象者間で同じ） | Uuid | はい |
| recTaskId | 現在の録音タスクのためのサーバー生成ID（対象者間で異なる） | 整数 | はい |
| taskName | 現在のタスクの名前 | 文字列 | はい |
| start_time | タスクの開始時間 | UNIXタイムスタンプ | はい |
3.6 試行データの記録
- ルート: /recordTrial
- タイプ: POST
- 呼び出されるとき: 試行が終了したとき OR カスタム記録アクションが実行されたとき
- Labvancedサーバーの機能: 外部APIリクエストが有効な場合は呼び出されません。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| recTaskId | 現在の録音タスクのためのサーバー生成ID（対象者間で異なる） | 整数 | はい |
| taskId | エディタで定義された現在のタスクのID（対象者間で同じ） | Uuid | はい |
| trailNr | 試行番号 | 整数 | はい |
| recData | メインデータ / 各試行ごとの全ユーザー作成変数はここに保存されます | JSON | はい |
注意: 各試行ごとに記録される正確なデータは、特定の実験とタスクに依存します。各研究の概要は、特定の実験の“変数”タブで入手可能です（スクリーンショットを参照）。また、外部APIの変数名はJSON構造内のキーとして使用されるため、変数名がユニークであることを確認してください。そうしないと、データが上書きされてしまいます。Labvancedシステムは通常、ユーザーがユニークな変数名を使用することを強制します。
3.7 実験の成功での終了
- ルート: /finishExpSession
- タイプ: POST
- 呼び出されるとき: 実験が正常に終了したとき
- Labvancedサーバーの機能: 研究を終了し、データセットに完了フラグを付けます（バランスに重要）。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| end_time | 実験が終了した時間 | UNIXタイムスタンプ | はい |
| var_data | “/addMetaInfo”ルートのvarデータと同じ（更新情報） | JSON | はい |
| nextStartTime | 次の開始時間（長期的な研究のみ） | UNIXタイムスタンプ | いいえ |
| nextEndTime | 次の終了時間（長期的な研究のみ） | UNIXタイムスタンプ | いいえ |
| reminderTime | 次の開始時間までの時間（長期的な研究のみ） | 時間文字列 | いいえ |
| selectedEmail | 参加 reminderを送信するためのメール（長期的な研究のみ） | メールアドレス | いいえ |
| emailReminder | 提出するreminderのタイミング（長期的な研究のみ） | 文字列 | いいえ |
3.8 失敗での実験の終了
- ルート: /errExpSession
- タイプ: POST
- 呼び出されるとき: 実験がエラーで中止されたとき
- Labvancedサーバーの機能: 研究を中止し、データセットに不完全フラグを付けます
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expId | 研究のユニーク識別子 | 整数 | はい |
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| err_msg | エラーメッセージ | 文字列 | はい |
3.9 バイナリ（音声またはビデオ）データのアップロード
- ルート: /file_upload
- タイプ: POST
- 呼び出されるとき: 音声またはビデオ録音オブジェクトに関連付けられたイベントシステム内でアップロードアクションが実行されるとき。 Labvancedサーバーの機能: 外部APIリクエストが有効な場合は呼び出されません。
- 注意: サーバーはこのルートの戻り値を送信する必要があります（下記で説明）。これが行われない場合、“onUploadComplete”トリガーが実行されず、実験が正しく伝播できません。また、このルートのデータは“multipart/form-data”としてエンコードされており、バイナリデータと非バイナリデータの両方を含んでいます。
- ペイロード: 次のフィールドを持つJSON:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| expSessionNr | この参加者の録音セッションのユニーク識別子（昇順でカウント） | 文字列 | はい |
| newFileName | ファイルを保存するための推奨ファイル名。このファイル名には関連する変数名と、現在のブロック、タスク、および試行番号が含まれます。 | 文字列 | はい |
| myFile | 実際のファイル / バイナリデータ | バイナリ | はい |
必要な応答:
| フィールド名 | 説明 | データ型 | 必須 |
|---|---|---|---|
| file_guid | 録音ファイルのためのグローバルユニーク識別子（guid）。これはサーバー側で生成され、ファイルに関連付けられて保存される必要があり、後でどのファイルがどの録音オブジェクトから来たのか理解しやすくなります。 | Uuid | はい |
| file_name | サーバーがファイルを保存するために使用した結果のファイル名。これは（クライアントがリクエストで提案したファイル名と同じである必要はありません）。これも関連変数に保存されます。 | 文字列 | はい |