Realtime 概述
Realtime 通过 WebSocket 将事件推送给已连接的客户端。您的服务器将事件发布到指定名称的频道，已订阅的客户端无需轮询即可收到该事件。
当客户端需要获取变化而无需再次发起请求时，可使用 Realtime，例如订单更新、聊天消息、仪表盘变化或已完成的后台任务。
频道、成员和连接
三个词描述了这一模型，它们不可互换。
channel（频道）是一个命名的房间。只要至少有一个连接在订阅，频道就会存在；最后一个连接离开时，频道随之消失。频道名称最多允许 164 个字母、数字以及以下字符：_ - = @ , . ;。
connection（连接）是一个打开的 WebSocket。连接建立时会获得一个 ID（26896.319537）。授权会对该 ID 进行签名，发布时可以将其排除在投递范围之外。
member（成员）是 presence 频道上经过身份验证的标识。一个成员可以持有多个连接，例如三个浏览器标签页。Presence 事件在该成员的第一个连接加入时和最后一个连接离开时触发，中间的标签页不会产生这些事件。
三种频道类型
频道名称前缀决定了频道类型及其授权行为。
| 名称 | 谁可以订阅 | 有成员 |
|---|---|---|
| orders | 持有 app key 的任何人 | 否 |
| private-orders | 仅限后端签名授权的客户端 | 否 |
| presence-lobby | 仅限后端签名授权的客户端 | 是 |
public 频道对持有 app key 的任何人可读，而 app key 会包含在客户端代码中。请仅发布每位访问者都可以看到的数据。参见公共频道。
private 频道要求您的后端审批每次订阅。客户端将连接 ID 和频道名称发送到您的端点，端点使用 app secret 计算签名并返回。参见私有频道。private-encrypted-… 频道还会使用您服务器持有的密钥对载荷进行加密。参见加密频道。
客户端接收的事件
应用事件由您定义：在发布时指定名称（order-updated、message.created），并为其绑定处理函数。除此之外，客户端还会在 bird: 前缀下重新触发生命周期事件，绑定方式与您自己的事件完全相同：
- bird:subscription_succeeded 在每个频道的订阅生效时触发一次。在 presence 频道上，它携带当前成员列表，因此您可以在任何人变动之前渲染房间。
- bird:member_added 和 bird:member_removed 在 presence 频道上随成员加入和离开而触发。member_added 在某人的第一个连接订阅时触发；member_removed 仅在其最后一个连接离开时触发。第二个标签页的打开和关闭不会产生这两个事件。
- bird:connection_count 报告有多少连接订阅了该频道（前提是应用启用了连接计数和连接计数事件）。它计数的是连接，因此拥有三个标签页的成员计为三。
- bird:subscription_error 在订阅被拒绝时触发，最常见的原因是授权失败。
以 client- 开头的名称保留给客户端之间直接发送的事件，这是一个独立的应用设置，且仅允许在私有和 presence 频道上使用。
您的服务器也可以通过 webhook 接收事件，例如频道变为有人或无人时，以及成员加入或离开时。这些事件以 realtime.* 事件的形式，通过与 Bird 其余部分相同的 webhook 端点送达。
客户端
三个客户端通过同一协议接收事件。浏览器和 Node.js 使用 @messagebird/realtime，iOS、macOS 和 Linux 使用 BirdRealtime，Android 和服务器端 JVM 使用 com.messagebird:bird-realtime。每个客户端都支持订阅、绑定、presence、signin() 和客户端事件。
请将 app secret 保存在您的服务器上。服务器端 SDK 使用它来发布事件、授权频道和断开成员连接。
应用、密钥和区域
应用是一个隔离的环境，拥有自己的凭证和独立的频道命名空间。两个应用永远看不到彼此的频道，因此应用是划分预发布环境和生产环境的正确边界。
每个应用使用创建时选定的不可变区域。使用列出 Realtime 区域获取可接受的标识符，并选择距离您的用户最近的区域。
每个应用有三个用途不同的值：
- app ID（rap_…）用于在 Bird API 调用中标识应用，并出现在每个 /v1/realtime/apps/… 路径中。
- key 是公开的。浏览器使用它进行连接，可以安全地包含在客户端代码中。
- secret 与 key 配对，用于验证服务器端调用和签署频道授权。它仅在创建时显示一次。持有 secret 的任何人都可以向您的应用发布消息并伪造 presence 身份。
在 Realtime 应用页面管理应用和轮换密钥。先创建第二个密钥并部署，然后撤销旧密钥。
可观测性
Realtime 指标页面按应用或跨工作区报告所选时间窗口内的三个值：
- 最大连接数是窗口内同一时刻打开的最高连接数。此峰值即为连接数限制所适用的值。
- 平均连接数是每日峰值的平均值，而非对每个采样点求平均。一个每天下午出现峰值、夜间空闲的工作区，其平均值会远高于安静时段。
- 消息数统计事件投递次数，每个频道计一次：一次发布指定了 50 个频道则计为 50。它还包含协议代您发送的事件，因此 presence 加入和连接计数更新也计入同一数字，这就是为什么该数值可能会超过您的代码实际发布的次数。
用量按一分钟为单位聚合，因此最近的流量可能需要几分钟才能显示。用量 API 目前仅在仪表盘中可用。如需通过编程方式获取可见性，请在您的系统中记录发布次数，或从 realtime.* webhook 中推导活动数据。
套餐与限制
免费套餐包含 100 个并发连接和每天 200,000 条消息，覆盖一个工作区的所有应用。创建更多应用不会提高上限，因为限制适用于整个工作区。
付费套餐起步价为每月 $25，包含 250 个并发连接和每天 500,000 条消息，最高可扩展至 30,000 个连接和每天 9,000 万条消息。Realtime 定价列出了所有档位。
每个请求的上限适用于所有套餐：一次发布最多指定 100 个频道，一个批次最多包含 10 个事件，单个事件载荷序列化后不超过 10 KB。
后续步骤
- 发送您的第一个 Realtime 事件带您端到端地走完整个流程。
- 发布事件介绍如何从服务器发布事件、批量发布以及排除发起请求的客户端。
- 授权频道是您的后端为私有和 presence 频道实现的契约。