要求授权连接

App key 是公开的。任何能加载你页面的人都可以用它打开连接并订阅公共频道。

授权连接要求每个新连接在 30 秒内证明自身已授权。Realtime 边缘节点会关闭未能及时授权的连接。

要求授权连接

在 Realtime apps 页面为应用启用 Authorized connections。你也可以通过 Realtime API 将 authorized_connections 设置为 true。该设置适用于使用该应用任一密钥的所有连接。

在生产环境启用此设置之前，先更新客户端以支持授权。启用前已建立的连接保持打开，但旧客户端的后续连接会在授权超时后失败。

什么算作已授权

新连接初始状态为未授权。以下任一操作可完成授权：

私有或 presence 订阅成功。 客户端将连接 ID 发送到你的 authEndpoint，你的后端对其签名，边缘节点验证签名。参见频道授权。
signin() 成功。 客户端将连接 ID 发送到你的 memberAuthEndpoint，并收到签名的成员身份。参见终止成员连接了解完整的登录流程。

两种方式证明的是同一件事：持有 app secret 的某方为该连接做了担保。订阅公共频道不能证明任何事，也不会完成授权。

仅使用公共频道的场景

仅订阅公共频道的客户端通常不需要联系你的后端。要求授权连接后，调用 signin()，使连接无需私有订阅即可完成授权：

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

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

await bird.signin();

const status = bird.subscribe("build-status");
status.bind("build-finished", (data) => render(data));

import BirdRealtime

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    memberAuthEndpoint: URL(string: "https://your-backend.example.com/bird/auth/member")
))

try await bird.signin()

let status = bird.subscribe("build-status")
status.bind("build-finished") { data in
    render(data)
}

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

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        memberAuthEndpoint = "https://your-backend.example.com/bird/auth/member",
    )
)

bird.signin() // suspending

val status = bird.subscribe("build-status")
status.bind("build-finished") { data ->
    render(data)
}

只需调用一次 signin()。每次重连后客户端会重新登录，因为身份属于该连接。当调用者不应连接时，从你的成员授权端点返回 403 Forbidden。

如果应用在加载时订阅了私有或 presence 频道，成功的订阅已经完成了连接授权。

客户端未授权时看到的结果

边缘节点使用代码 4009 和原因 Connection not authorized within timeout 关闭连接。客户端不会重试此范围内的代码，因此连接进入 failed 状态。

bird.connection.bind("error", ({ code, message }) => {
  if (code === 4009) console.warn(message);
});

bird.onError { error in
    if error.code == 4009 { print(error.message) }
}

bird.onError { error ->
    if (error.code == 4009) println(error.message)
}

代码 4009 也用于标识被你的后端终止连接的成员。在选择登录或已登出状态之前，请检查原因。参见终止成员连接和连接生命周期与重连。

连接在完成授权之前不计入应用的连接配额。

授权范围

要求授权连接控制的是谁可以保持连接打开。它不会替代授权检查，也不会改变谁可以读取频道：

公共频道对每个已授权的连接仍然是公共的。如果事件属于某个客户，请使用私有频道并在端点中检查频道名称。
你自己的授权端点为谁签名，谁就被授权，因此一个宽松的端点会像 app key 一样随意发放授权。

后续步骤

频道授权是你的后端为私有和 presence 订阅计算的签名。
私有频道是事件本身属于特定用户时的正确选择。
终止成员连接涵盖 signin() 以及 4009 的另一种用途。
向成员发送事件将事件发送给已登录的身份，而非频道。
连接生命周期与重连解释了为什么 4009 是终止状态。

要求授权连接