Swift SDK

BirdRealtime 是 Bird Realtime 的官方 Swift 客户端：它与 Bird 边缘节点保持一条 WebSocket 连接，订阅频道，并在事件发布时将其送达。它是手写的而非自动生成的，因为 Realtime 是 WebSocket 数据平面而非 REST 接口，且它与浏览器客户端使用相同的线路协议。

它没有外部依赖（传输层使用 URLSessionWebSocketTask，帧处理使用 JSONSerialization），可在 iOS 15+、macOS 12+、tvOS 15+、watchOS 8+ 及 Linux 上运行。

此客户端是接收端。发布事件、授权频道和终止连接都是 Bird API 上的服务端操作；参见发布事件。

安装

在 Xcode 中，选择 File > Add Package Dependencies 并输入仓库 URL。在 Package.swift 中：

代码示例

dependencies: [
    .package(url: "https://github.com/messagebird/bird-sdk-swift.git", from: "0.1.0")
]

然后将产物添加到使用它的 target 中：

代码示例

.target(
    name: "YourApp",
    dependencies: [.product(name: "BirdRealtime", package: "bird-sdk-swift")]
)

构建客户端

代码示例

import BirdRealtime

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

只有 appKey 是必需的，另外需要 region（us1 或 eu1，用于解析边缘主机）或显式指定 wsHost。应用密钥是公开的，可以写在客户端代码中：它用于标识应用，不承担任何授权功能。除非你传入 deliveryQueue，否则回调在主队列上运行。

订阅频道

代码示例

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

名称不含 private- 或 presence- 前缀的频道是公开的：任何持有应用密钥的客户端都可以订阅，因此请将其内容视为能打开你应用的任何人都可读取。

私有频道和 presence 频道

私有和 presence 频道由持有应用密钥的后端授权。将客户端指向你的端点：它会 POST {"connection_id", "channel_name"}，并期望返回 {"auth", "member_data"?}。

代码示例

let bird = BirdRealtime(options: .init(
    appKey: "your-app-key",
    region: "us1",
    authEndpoint: URL(string: "https://your-backend.example.com/bird/auth")!,
    authHeaders: ["authorization": "Bearer <session token>"]
))

guard let room = bird.subscribe("presence-room-42") as? PresenceChannel else { return }
room.bind(BirdProtocol.Event.subscriptionSucceeded) { _ in
    print("me:", room.myId ?? "?", "members:", Array(room.members.keys))
}
room.bind(BirdProtocol.Event.memberAdded) { member in
    print("joined:", member ?? "")
}

改为传入 authorizer 闭包，即可通过你自己的网络层完成签名。

来自服务器的拒绝（签名错误、应用超出容量）会出现在连接上而非频道上，因为线路协议不携带频道归属信息。通过 onError 监听这些事件。身份验证器内部的失败则会在频道上触发 bird:subscription_error。

登录成员

signin() 告知边缘节点此连接属于哪个成员。该身份使 API 能够向成员发送消息或终止其连接，也是满足要求授权连接的应用配置所必需的。

代码示例

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

let me = try await bird.signin()
print("signed in as", me.memberId)

bird.member.bind("order.shipped") { data in
    print("addressed to me:", data ?? "")
}

调用 signin() 一次即可。身份会保留在连接上，因此客户端在重连后会自动重新登录。自动登录失败时没有活跃的调用可以抛出异常，因此错误会出现在 onSigninError 上。这样可以防止成员端点故障干扰频道订阅。

连接生命周期

代码示例

bird.onConnectionStateChange { previous, current in
    print("connection: \(previous) → \(current)")
}
bird.onError { error in
    if error.code == 4009 { print("session ended elsewhere") }
}

重连是自动的，采用从 1 秒到 30 秒上限的全抖动指数退避。关闭码 4000–4099 表示拒绝且不可恢复：客户端会停止并报告该码，因为拒绝是一个决定而非瞬时故障。码 4200–4299 立即重连；其他码则进行退避。每次重连时频道都会使用新的授权重新订阅。参见连接生命周期。

对所有非回环主机，传输层使用 TLS。allowInsecure 仅允许 localhost、127.0.0.1 和 [::1] 使用 ws://，因此从开发目标复制的配置不会静默降级生产流量。

客户端事件

启用应用的客户端事件设置后，订阅了私有或 presence 频道的客户端可以直接向其对等端发布消息：

代码示例

try room.trigger("client-typing", data: ["on": true])

参见客户端事件。

源码

github.com/messagebird/bird-sdk-swift，MIT 许可证。请在该仓库中报告问题。

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

获取实施简报

相关资源