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，包含以下字段：

注意： 不需要在外部服务器上实现，因为这只初始化从Labvanced服务器到客户端计算机的实验加载

3.2 组和会话选择

• 路由： /startFirstPlayerSession
• 类型： POST
• 调用时： 路由3.1“/startExpPlayer”从Labvanced服务器成功返回时。
• Lavanced服务器上的主要功能： 用于将组和会话编号分配给参与者（服务器侧平衡）。
• 有效负载： JSON，包含以下字段：

3.3 实验开始

• 路由： /setPlayerSessionStartedTime
• 类型： POST
• 调用时： 当参与者按下“开始实验”时
• Lavanced服务器上的功能： 保存实验的开始时间、会话和组名，并开始实验。
• 有效负载： JSON，包含以下字段：

3.4 添加元数据

• 路由： /addMetaInfo
• 类型： POST
• 调用时： 当参与者按下“开始实验”时
• Lavanced服务器上的功能： 在服务器上保存元信息。
• 有效负载： JSON，包含以下字段：

3.5 记录任务信息

• 路由： /recordStartTask
• 类型： POST
• 调用时： 实验流程中开始一个新任务时
• Lavanced服务器上的功能： 当启用外部API请求时不被调用
• 有效负载： JSON，包含以下字段：

3.6 记录试次数据

• 路由： /recordTrial
• 类型： POST
• 调用时： 试次完成或执行自定义记录操作时
• Lavanced服务器上的功能： 当启用外部API请求时不被调用。
• 有效负载： JSON，包含以下字段：

注意： 每个试次记录的数据的确切内容取决于具体实验和任务。每项研究的概述可以在具体实验的“变量”选项卡下找到（见截图）。还请注意，外部API变量名称将在JSON结构中用作键。因此，请确保变量名称是唯一的。否则您将覆盖数据。Labvanced系统通常要求用户使用唯一的变量名称。

3.7 成功完成实验

• 路由： /finishExpSession
• 类型： POST
• 调用时： 实验成功完成时
• Lavanced服务器上的功能： 完成研究并将数据集标记为已完成（对平衡很重要）。
• 有效负载： JSON，包含以下字段：

3.8 实验失败

• 路由： /errExpSession
• 类型： POST
• 调用时： 实验以错误终止
• Lavanced服务器上的功能： 中止研究并将数据集标记为不完整
• 有效负载： JSON，包含以下字段：

3.9 上传二进制（音频或视频）数据

• 路由： /file_upload
• 类型： POST
• 调用时： 在与某些音频或视频录制对象相关联的事件系统中执行上传操作时。 Lavanced服务器上的功能：当启用外部API请求时不被调用。
• 注意： 服务器必须为此路由发送返回值（如下所述）。如果不这样做，“onUploadComplete”触发器将不会执行，实验将无法正确传播。还要注意，此路由中的数据编码为“multipart/form-data”，因为它同时包含二进制和非二进制数据。
• 有效负载： JSON，包含以下字段：

所需响应：