Swift SDK

BirdRealtime adalah klien Swift resmi untuk Bird Realtime: klien ini mempertahankan WebSocket ke edge Bird, subscribe ke channel, dan mengirimkan event saat dipublikasikan. Klien ini ditulis manual, bukan di-generate, karena Realtime adalah data plane WebSocket dan bukan surface REST, serta menggunakan dialek wire yang sama dengan klien browser.

Klien ini tidak memiliki dependensi (URLSessionWebSocketTask untuk transport, JSONSerialization untuk frame) dan berjalan di iOS 15+, macOS 12+, tvOS 15+, watchOS 8+, dan Linux.

Klien ini adalah sisi penerima. Mempublikasikan event, mengotorisasi channel, dan memutus koneksi adalah operasi sisi server pada Bird API; lihat mempublikasikan event.

Instal

Di Xcode, pilih File > Add Package Dependencies dan masukkan URL repositori. Di sebuah Package.swift:

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

Kemudian tambahkan product ke target yang menggunakannya:

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

Membuat klien

import BirdRealtime

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

Hanya appKey yang wajib, ditambah region (us1 atau eu1, yang me-resolve host edge) atau wsHost eksplisit. App key bersifat publik dan disertakan dalam kode klien: ia mengidentifikasi aplikasi, bukan mengotorisasi apa pun. Handler berjalan di main queue kecuali Anda meneruskan deliveryQueue.

Subscribe ke channel

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

Channel yang namanya tidak memiliki prefix private- atau presence- bersifat publik: klien mana pun dengan app key dapat subscribe, jadi anggap isinya dapat dibaca oleh siapa saja yang bisa membuka aplikasi Anda.

Channel private dan presence

Channel private dan presence diotorisasi oleh backend Anda, yang menyimpan app secret. Arahkan klien ke endpoint Anda: klien melakukan POST {"connection_id", "channel_name"} dan mengharapkan {"auth", "member_data"?} sebagai respons.

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 ?? "")
}

Teruskan closure authorizer sebagai gantinya untuk menandatangani melalui networking stack Anda sendiri.

Penolakan dari server (signature tidak valid, aplikasi melebihi kapasitas) tiba di koneksi, bukan di channel, karena wire tidak membawa atribusi channel. Pantau hal tersebut dengan onError. Kegagalan di dalam authorizer Anda memang mengemit bird:subscription_error pada channel.

Sign in member

signin() memberi tahu edge member mana yang dimiliki koneksi ini. Identitas tersebut memungkinkan API mengirim ke member atau memutus koneksi mereka, dan memenuhi persyaratan aplikasi yang dikonfigurasi untuk mewajibkan koneksi terotorisasi.

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 ?? "")
}

Panggil signin() sekali. Identitas tetap berada di koneksi, sehingga klien sign in kembali secara otomatis setelah reconnect. Sign-in otomatis yang gagal tidak memiliki panggilan aktif untuk melakukan throw, sehingga muncul di onSigninError. Ini mencegah endpoint member yang bermasalah mengganggu subscription channel.

Siklus hidup koneksi

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

Reconnect berjalan otomatis, dengan exponential backoff full-jitter dari 1 detik hingga batas 30 detik. Close code dalam rentang 4000–4099 adalah penolakan dan bersifat terminal: klien berhenti dan melaporkan kode tersebut, karena penolakan adalah keputusan, bukan kegagalan sementara. Kode dalam rentang 4200–4299 langsung reconnect; kode lainnya melakukan backoff. Channel melakukan re-subscribe dengan otorisasi baru pada setiap reconnect. Lihat siklus hidup koneksi.

Transport menggunakan TLS untuk setiap host non-loopback. allowInsecure mengizinkan ws:// hanya untuk localhost, 127.0.0.1, dan [::1], sehingga konfigurasi yang disalin dari target pengembangan tidak dapat secara diam-diam menurunkan keamanan traffic produksi.

Client event

Dengan pengaturan client-events aplikasi diaktifkan, klien yang subscribe ke channel private atau presence dapat mempublikasikan langsung ke peer-nya:

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

Lihat client event.

Sumber

github.com/messagebird/bird-sdk-swift, berlisensi MIT. Laporkan masalah di sana.