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 数据格式: 所有路由中,数据都以 JSON 格式发送,除了“/file_upload”路由。“/file_upload”路由(用于上传二进制文件,如录制的视频或音频)采用“multipart/form-data”编码,因此请确保您正确解析传入的数据为 JSON 或 multipart/form-data / 二进制数据。
2.2 CORS 设置: 在实现后端时,您必须实现/允许跨域资源共享(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” 仅发送到 Labvanced 服务器,以加载实验定义/JSON 文件和相关刺激。
- 端点 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 时。Lavanced 服务器上的主要功能:初始化实验加载。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
isTestrun | 数据是否已记录 | 布尔 | 否 |
subject_code | 通过 URL 参数标识主题 | 字符串 | 否 |
token | 纵向研究中参与者的唯一标识符 | 令牌标识符 | 否 |
askSubjData | 是否展示初始调查,所用以将主题分到不同组别 | 布尔 | 是 |
注意: 不需要在外部服务器上实现,因为这仅初始化从 Labvanced 服务器到客户端计算机的实验加载。
3.2 组和会话选择
- 路由: /startFirstPlayerSession
- 类型: POST
- 调用时: 当路由 3.1 “ /startExpPlayer” 从 Labvanced 服务器成功返回时。
- Lavanced 服务器上的主要功能: 将组和会话编号分配给主题(服务器端平衡)。
- 有效载荷: 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
- 调用时: 参与者按下“开始实验”时。
- Lavanced 服务器上的功能: 保存实验的开始时间、会话和组名称并开始实验。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
start_time | 实验开始时间 | UNIX 时间戳 | 是 |
sessionNr | 纵向研究中的会话编号 | 整数 | 是 |
groupNr | 此主题的组编号 | 整数 | 是 |
token | 纵向研究中参与者的唯一标识符 | 令牌标识符 | 否 |
3.4 添加元数据
- 路由: /addMetaInfo
- 类型: POST
- 调用时: 参与者按下“开始实验”时。
- Lavanced 服务器上的功能: 在服务器上保存元信息。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
var_data | 包含元信息的 JSON | JSON | 是 |
var_data.browserSpec | 主题使用的浏览器 | 字符串 | 否 |
var_data.versionSpec | 主题使用的浏览器版本 | 字符串 | 否 |
var_data.systemSpec | 主题使用的设备类型/操作系统 | 字符串 | 否 |
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
- 调用时: 实验流程中开始新任务时。
- Lavanced 服务器上的功能: 当激活外部 API 请求时不被调用。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
blockNr | 当前区块编号(递增计数器) | 整数 | 是 |
blockId | 当前区块的唯一 ID | Uuid | 是 |
blockName | 区块名称 | 字符串 | 是 |
taskNr | 当前任务编号(递增计数器) | 整数 | 是 |
taskId | 在编辑器中定义的当前任务的 ID(在主题之间相同) | Uuid | 是 |
recTaskId | 当前录音任务的服务器生成 ID(在主题之间不同) | 整数 | 是 |
taskName | 当前任务的名称 | 字符串 | 是 |
start_time | 任务开始时间 | UNIX 时间戳 | 是 |
3.6 记录试验数据
- 路由: /recordTrial
- 类型: POST
- 调用时: 实验结束或执行自定义记录操作时。
- Lavanced 服务器上的功能: 当激活外部 API 请求时不被调用。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
recTaskId | 当前录音任务的服务器生成 ID(在主题之间不同) | 整数 | 是 |
taskId | 在编辑器中定义的当前任务的 ID(在主题之间相同) | Uuid | 是 |
trailNr | 试验编号 | 整数 | 是 |
recData | 存储所有用户创建的每个试验的主要数据 | JSON | 是 |
注意: 每个试验记录的确切数据取决于具体实验和任务。有关每个研究的概述,请在具体实验的“变量”选项卡中查看(请参见屏幕截图)。同时,请注意外部 API 变量名称将用作 JSON 结构中的键。因此,请确保变量名称是唯一的。否则,您将覆盖数据。Labvanced 系统通常强制用户使用唯一的变量名称。
3.7 成功完成实验
- 路由: /finishExpSession
- 类型: POST
- 调用时: 实验顺利完成时。
- Lavanced 服务器上的功能: 完成研究并将数据集标记为已完成(对平衡很重要)。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
end_time | 实验结束时间 | UNIX 时间戳 | 是 |
var_data | 与 “/addMetaInfo” 路由中的 var 数据相同(更新的信息) | JSON | 是 |
nextStartTime | 下一个开始时间(仅适用于纵向研究) | UNIX 时间戳 | 否 |
nextEndTime | 下一个结束时间(仅适用于纵向研究) | UNIX 时间戳 | 否 |
reminderTime | 距下一次开始时间的时间(仅适用于纵向研究) | 时间字符串 | 否 |
selectedEmail | 发送参与提醒的电子邮件(仅适用于纵向研究) | 电子邮件地址 | 否 |
emailReminder | 何时发送提醒(仅适用于纵向研究) | 字符串 | 否 |
3.8 以失败完成实验
- 路由: /errExpSession
- 类型: POST
- 调用时: 实验因错误而中止时。
- Lavanced 服务器上的功能: 中止研究并将数据集标记为未完成。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expId | 研究的唯一标识符 | 整数 | 是 |
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
err_msg | 错误信息 | 字符串 | 是 |
3.9 上传二进制(音频或视频)数据
- 路由: /file_upload
- 类型: POST
- 调用时: 在与某些音频或视频录制对象关联的事件系统中执行上传操作时。 Lavanced 服务器上的功能:当激活外部 API 请求时不被调用。
- 注意: 服务器必须为此路由发送返回值(如下所述)。如果没有这样做,“onUploadComplete” 触发器将不会执行,实验无法正确传播。同时请注意,该路由中的数据以“multipart/form-data”编码,因为它包括二进制和非二进制数据。
- 有效载荷: JSON,包含以下字段:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
expSessionNr | 参与此参与者的录音会话的唯一标识符(向上计数) | 字符串 | 是 |
newFileName | 存储文件的建议文件名。文件名包括关联的变量名称,以及当前的区块、任务和试验编号。 | 字符串 | 是 |
myFile | 实际文件/二进制数据 | 二进制 | 是 |
所需响应:
字段名称 | 描述 | 数据类型 | 必需 |
---|---|---|---|
file_guid | 记录文件的全球唯一标识符(guid)。必须在服务器端生成,并将保存在与文件关联的变量中,以便后续容易理解哪个文件来自哪个录音对象。 | Uuid | 是 |
file_name | 服务器用于保存文件的结果文件名。这可以与客户端请求中建议的文件名相同,但不一定是。这个也将存储在关联变量中。 | 字符串 | 是 |