将实时事件推送到已连接的 浏览器和移动应用。
通过托管的发布/订阅频道推送实时订单更新、AI 智能体令牌流、协作房间状态和应用内通知，无需自行运维 WebSocket 基础设施。客户端订阅时频道按需创建，最后一个连接断开时自动关闭。公共、私有、在线状态、加密和缓存模式直接由频道名称决定。
channels.ts
已订阅 4 个已订阅 4 个const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" }); // Public: anyone holding the app key can subscribe.const scores = bird.subscribe("match-42"); // Private: your backend signs every subscription.const order = bird.subscribe("private-order-ord_123"); // Presence: private, plus an identity the room can see.const room = bird.subscribe("presence-room-42"); // Cache: the latest event replays to whoever joins next.const build = bird.subscribe("cache-build-8821"); build.bind("bird:cache_miss", () => showSkeleton());
连接 26896.319537
channels.ts
已订阅 4 个已订阅 4 个const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" }); // Public: anyone holding the app key can subscribe.const scores = bird.subscribe("match-42"); // Private: your backend signs every subscription.const order = bird.subscribe("private-order-ord_123"); // Presence: private, plus an identity the room can see.const room = bird.subscribe("presence-room-42"); // Cache: the latest event replays to whoever joins next.const build = bird.subscribe("cache-build-8821"); build.bind("bird:cache_miss", () => showSkeleton());
连接 26896.319537
channels.ts
已订阅 4 个已订阅 4 个const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" }); // Public: anyone holding the app key can subscribe.const scores = bird.subscribe("match-42"); // Private: your backend signs every subscription.const order = bird.subscribe("private-order-ord_123"); // Presence: private, plus an identity the room can see.const room = bird.subscribe("presence-room-42"); // Cache: the latest event replays to whoever joins next.const build = bird.subscribe("cache-build-8821"); build.bind("bird:cache_miss", () => showSkeleton());
连接 26896.319537
用频道前缀限定访问权限和房间行为。
按需创建房间，无需预先配置频道注册表。
在 Bird Realtime API 上，你的应用通过订阅频道名称来路由实时流量，无需在数据库中预先创建房间。频道名称区分大小写，最长 164 个字符。名称前缀决定安全和状态边界：无前缀的名称对任何访客开放；private- 要求你的后端为订阅者授权；presence- 会增加经过验证的成员名单；private-encrypted- 会对事件载荷进行端到端加密。由于任何人都可以使用你的公共应用密钥加入公共频道，请将客户和租户标识符放在需要授权的前缀下。
根据推送内容选择频道模式。
公共广播、需认证的客户数据流和协作房间都使用同一个 WebSocket 连接和同一个后端发布调用。
- 01
公开频道。
向任何访客广播实时体育比分、公交到站信息、库存行情或系统状态更新，无需调用授权端点。由于任何持有你公共应用密钥的人都能订阅，请使用 scores-live 这类通用主题名称，不要在公共频道名称中包含客户 ID。
- 02
私有频道。
通过 private- 频道推送个人订单追踪、AI 智能体令牌流、账单提醒和工作区通知。浏览器或移动应用订阅时，你的后端会检查用户会话，并用应用密钥对订阅签名，使未授权的连接无法监听。
- 03
存在感知频道。
在 presence- 频道上构建协作文档成员名单、实时观看者栏和客服队列可用状态。你的服务器为每个订阅者授权并附加经过验证的成员资料，已连接的客户端即可收到当前房间成员名单以及实时的加入和离开更新。
- 04
加密频道。
使用 private-encrypted- 频道保护敏感的账户更新、财务通知或机密工作区数据。你的服务器使用你持有的 32 字节主密钥加密每个载荷，通过 Realtime 边缘节点传送密文，同时保留频道和事件名称可见以便路由。
- 05
缓存频道。
添加 cache- 前缀后，后加入的用户和重新连接的移动客户端在订阅时即可获得最新状态。Realtime 会重放最近一次发布的事件，TTL 最长 30 分钟；缓存为空时会触发 cache-miss webhook，让你的服务器重新填充完整的状态快照。
一次调用即可将后端事件扇出到最多 100 个频道。
从你的后端或后台任务通过标准的 HTTP 请求发布更新，由 Bird 负责向已连接的浏览器和设备进行 WebSocket 扇出。一次调用可将一个事件广播到最多 100 个频道（例如实时比赛数据流及其缓存副本），也可为不同房间批量发送最多 10 个不同事件。如果界面已应用乐观更新，你可以跳过发起操作的标签页的连接；可以在发布响应中返回实时连接数或成员数；还可以附加幂等键，避免网络重试导致重复投递事件。
// One event, up to 100 channels, one request.
const result = await bird.realtime.publish(APP_ID, {
event: "score-updated",
channels: ["match-42", "cache-match-42"],
data: { home: 2, away: 1 },
// The tab that scored already rendered it locally.
exclude_connection_id: "26896.319537",
include: ["connection_count"],
});
for (const channel of result.data ?? []) {
console.log(channel.name, channel.connection_count);
}
在参与者之间实时传递输入状态提示和光标位置。
输入状态提示、实时指针坐标和当前选区高亮等临时界面信号无需经过你的后端往返。为应用启用客户端事件后，私有或在线状态房间中已授权的订阅者可以直接向房间内其他参与者广播 client- 前缀的事件，每个连接每秒最多 10 条消息。由于必须使用需认证的频道，匿名访客无法借助你的公共应用密钥进行广播，高频的点对点信号也不会占用你的应用服务器。
将低延迟的事件扇出与持久化的应用状态结合使用。
Realtime 边缘节点一旦接受事件，发布即视为成功，随后事件会异步扇出给当前已连接的订阅者。实时频道只推送传输中的更新，不会为离线设备保存消息队列，因此请将持久记录保存在你的数据库中，并通过发布事件或缓存频道同步已连接的界面。所有套餐的限制一致：每次发布最多 100 个频道，每批最多 10 个事件，每个事件载荷最大 10 KB，频道名称最长 164 个字符。
在文档中深入了解。
阅读 Realtime 概览，了解频道、成员和连接之间的关系。参阅以下指南：发布事件，了解多频道扇出和乐观更新界面排除；缓存频道，了解为后加入者重放状态和缓存未命中恢复；查询频道状态，了解如何从后端检查实时房间占用情况。
继续构建
使用 Realtime。
将发布/订阅频道与实时在线名单、服务器签名的访问控制和后端生命周期 webhook 结合使用。
规模扩展
不失控。
在工作区中组织团队，控制 API 访问权限，通过审计日志追踪变更。
组织
Harbor
访问权限仅限于其所在工作区。
生产环境/API 密钥
Harbor 后端
活跃Alex Lee
管理员
今天 · UTC
审计日志
组织
Harbor
访问权限仅限于其所在工作区。
生产环境/API 密钥
Harbor 后端
活跃Alex Lee
管理员
今天 · UTC
审计日志
组织
Harbor
访问权限仅限于其所在工作区。
生产环境/API 密钥
Harbor 后端
活跃Alex Lee
管理员
今天 · UTC
审计日志