发送你的第一个实时事件

Realtime 通过 WebSocket 传递事件。你的服务器向频道发布消息，每个已订阅该频道的已连接客户端都会收到事件。本指南只走一条路径：创建应用、订阅客户端、从服务器发布。

免费计划涵盖 100 个并发连接和每天 200,000 条消息，适用于一个工作区内的所有应用。付费计划起价每月 $25；详见 Realtime 定价。

1. 创建应用

应用是一个拥有独立凭据和频道的隔离环境。创建时选择区域，之后无法更改。

在控制台中打开 Realtime > Apps。
点击 Create app。
在 Name 中输入名称。
选择一个 Region：United States (us1) 或 Europe (eu1)。
点击 Create app。

随后 Save your app credentials 会显示三个值，且仅显示一次：

App ID 是一个 rap_… id，用于在 Bird API 调用中标识应用。
Key 是公开的。客户端使用它连接，可以安全地包含在客户端代码中。
Secret 与 Key 配对，用于验证服务端调用和签名频道授权。请像对待密码一样保管它。

在点击 I've saved my secret 之前，请复制全部三个值，因为 Secret 不会再次显示。然后在 Developers > API keys 页面创建一个具有 realtime 权限的 Bird API 密钥，并导出后续步骤所需的内容：

代码示例

export BIRD_API_KEY="bk_us1_..."
export BIRD_REALTIME_KEY="your-app-key"
export BIRD_REALTIME_SECRET="your-app-secret"

2. 从客户端订阅

可从三个客户端中选择，每个平台一个，均使用相同协议：@messagebird/realtime 用于浏览器，BirdRealtime 用于 Apple 平台，com.messagebird:bird-realtime 用于 Android 和服务器 JVM。

npm install @messagebird/realtime

// Package.swift, or Xcode's File › Add Package Dependencies
dependencies: [
    .package(url: "https://github.com/messagebird/bird-sdk-swift.git", from: "0.1.0")
]

// build.gradle.kts
dependencies {
    implementation("com.messagebird:bird-realtime:0.1.3")
}

客户端通过 key 识别应用，并根据区域选择边缘节点，因此你无需配置主机：

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
});

const orders = bird.subscribe("orders");
orders.bind("order-updated", (data) => {
  console.log("order changed", data);
});

import BirdRealtime

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1"
))

let orders = bird.subscribe("orders")
orders.bind("order-updated") { data in
    print("order changed", data ?? "")
}

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
    )
)

val orders = bird.subscribe("orders")
orders.bind("order-updated") { data ->
    println("order changed: $data")
}

三个客户端在构造时即打开 socket，因此你无需单独调用连接即可订阅。在 socket 就绪之前订阅也没问题：频道会在本地注册，并在连接建立后立即发送，每次重连后也会重新发送。

orders 是公共频道，任何拥有应用 key 的客户端都可以订阅。名称为 private-… 或 presence-… 的频道需要你的服务器对每次订阅进行授权。参见授权频道。

频道无需在任何地方创建或配置。一个频道在至少有一个连接订阅时存在，当最后一个连接离开时消失。

3. 从服务器发布

发布是一个服务器端调用。它通过你的 Bird API key 进行身份验证，并携带应用的 key 和 secret，以便边缘节点接受请求。切勿从客户端发布，因为那意味着暴露 secret。

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
  },
});

await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order-updated",
  channels: ["orders"],
  data: { id: 42, status: "shipped" },
});

import os

from bird import Bird

client = Bird(
    api_key=os.environ["BIRD_API_KEY"],
    realtime_key=os.environ["BIRD_REALTIME_KEY"],
    realtime_secret=os.environ["BIRD_REALTIME_SECRET"],
)

client.realtime.publish(
    "rap_01krdgeqcxet5s7t44vh8rt9mg",
    event="order-updated",
    channels=["orders"],
    data={"id": 42, "status": "shipped"},
)

client, err := bird.NewClient(
	option.WithAPIKey(os.Getenv("BIRD_API_KEY")),
	option.WithRealtimeCredentials(os.Getenv("BIRD_REALTIME_KEY"), os.Getenv("BIRD_REALTIME_SECRET")),
)
if err != nil {
	log.Fatal(err)
}

_, err = client.Realtime.Publish(context.Background(), "rap_01krdgeqcxet5s7t44vh8rt9mg", bird.RealtimePublishParams{
	Event:    "order-updated",
	Channels: []string{"orders"},
	Data:     map[string]any{"id": 42, "status": "shipped"},
})
if err != nil {
	log.Fatal(err)
}

use MessageBird\Bird;
use MessageBird\RealtimeOptions;
use MessageBird\Wire\Model\RealtimePublish;

$bird = new Bird(
    getenv('BIRD_API_KEY') ?: '',
    realtime: new RealtimeOptions(
        key: getenv('BIRD_REALTIME_KEY') ?: '',
        secret: getenv('BIRD_REALTIME_SECRET') ?: '',
    ),
);

$bird->realtime->publish('rap_01krdgeqcxet5s7t44vh8rt9mg', (new RealtimePublish())
    ->setEvent('order-updated')
    ->setChannels(['orders'])
    ->setData(['id' => 42, 'status' => 'shipped']));

curl -X POST https://us1.platform.bird.com/v1/realtime/apps/rap_01krdgeqcxet5s7t44vh8rt9mg/events \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "X-Realtime-Key: $BIRD_REALTIME_KEY" \
  -H "X-Realtime-Secret: $BIRD_REALTIME_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order-updated",
    "channels": ["orders"],
    "data": { "id": 42, "status": "shipped" }
  }'

边缘节点投递事件后，已订阅的客户端会打印 order changed { id: 42, status: 'shipped' }。如果没有收到，请检查客户端 key 和服务器凭据是否属于同一个应用，以及频道名称是否完全匹配。一次发布最多可指定 100 个频道。要在一个请求中发送最多 10 个不同的事件，请参见批量发布。

发布在边缘节点接受事件后即完成。向已连接客户端的投递是异步的，因此 200 表示已接受，而非已送达。

4. 在仪表板中查看

Realtime > Metrics 显示按应用或整个工作区统计的峰值和平均并发连接数及消息数。图表报告每日使用数据点，因此请使用步骤 3 中的客户端输出来确认事件是否到达。

后续步骤

授权频道介绍了私有频道和在线状态频道，以及你的后端返回的签名。
发布事件包含完整的请求和响应，包括发布时每个频道的状态。
Webhooks 与事件介绍了如何在你自己的端点上接收 realtime.* 事件，例如频道变为已占用或成员加入。

继续查看此主题的文档、指南和示例。

动手实践并获取实施简报