事件 ​

Satori 协议规定了两套事件服务，分别基于 WebSocket 和 WebHook。你可以根据自己的需要进行选择。

类型定义 ​

Event ​

事件中的各属性遵循 资源提升 规则。

WebSocket ​

WebSocket 服务用于在 Satori SDK 与应用之间维护一个持久的、有状态的链接。通过这个链接，Satori 应用可以实时接收 SDK 推送的事件。

WebSocket 服务的地址为 /{path}/{version}/events。其中，path 为部署路径 (可以为空)，version 为 API 的版本号。

目前 Satori 仅有 v1 一个版本。

连接流程 ​

总的来说，Satori 应用需要在连接后遵循以下步骤：

1. 连接建立后，在 10s 内发送一个 IDENTIFY 信令，用于鉴权和恢复会话；
   SDK 收到后会回复一个 READY 信令，并开启事件推送；
2. 连接建立后，每隔 10s 向 SDK 发送一次 PING 信令；
   SDK 收到后会回复一个 PONG 信令；
3. 应用持续接收来自 SDK 的 EVENT 信令，用于接收事件。

信令的数据结构如下：

信令类型如下：

IDENTIFY 信令的 body 数据结构如下：

READY 信令的 body 数据结构如下：

EVENT 信令的 body 数据结构参见 Event。

鉴权 ​

WebSocket 鉴权通过 IDENTIFY 信令的 token 字段来实现。其中涉及的鉴权令牌由 SDK 分发，本协议不做任何限制。

如果 SDK 没有配置鉴权，则应用无需提供上述字段。

会话恢复 ​

当连接短暂中断时，Satori 应用可以通过 IDENTIFY 信令的 sequence 字段来恢复会话。sequence 字段的值为上一次连接中最后一个接收到的 EVENT 信令的 id 字段。会话恢复后，SDK 会向应用推送所有在断开连接期间发生的事件。

WebHook 可选 ​

WebHook 服务是指，Satori SDK 在接收到平台事件时，向应用提供的 HTTP 地址推送事件。一个 SDK 应当可以配置多个 WebHook，并允许应用对发送者进行鉴权。这些 WebHook 的配置方式由 SDK 自身决定，本协议规范化了一组 管理接口，但不做强制要求。

事件推送以 POST 的形式进行，参数以 application/json 的形式编码在请求体中。数据结构参见 Event。

应用收到 WebHook 请求时，如果能够顺利鉴权并处理请求，应当返回 2XX 的状态码。如果鉴权失败，应当返回 4XX 的状态码。如果处理失败，应当返回 5XX 的状态码。

反向鉴权 ​

Satori 应用可以要求 SDK 在发送 WebHook 请求时附带一个 Authorization 请求头，格式为 Bearer {token}。其中，token 由应用进行分发。