Swift SDK

BirdRealtime ist der offizielle Swift-Client für Bird Realtime: Er hält eine WebSocket-Verbindung zur Bird-Edge, abonniert Channels und liefert Events, sobald sie veröffentlicht werden. Er ist handgeschrieben statt generiert, weil Realtime eine WebSocket-Datenebene und keine REST-Oberfläche ist, und er spricht denselben Drahtdialekt wie der Browser-Client.

Er hat keine Abhängigkeiten (URLSessionWebSocketTask für den Transport, JSONSerialization für Frames) und läuft auf iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ und Linux.

Dieser Client ist die empfangende Seite. Events veröffentlichen, Channels autorisieren und Verbindungen beenden sind serverseitige Operationen auf der Bird API; siehe Events veröffentlichen.

Installation

Wählen Sie in Xcode File > Add Package Dependencies und geben Sie die Repository-URL ein. In einem Package.swift:

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

Fügen Sie dann das Produkt dem Target hinzu, das es verwendet:

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

Client erstellen

import BirdRealtime

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

Nur appKey ist erforderlich, dazu entweder region (us1 oder eu1, das den Edge-Host auflöst) oder ein expliziter wsHost. Der App-Key ist öffentlich und wird im Client-Code ausgeliefert: Er identifiziert die App, autorisiert aber nichts. Handler laufen auf der Main-Queue, sofern Sie keine deliveryQueue übergeben.

Einen Channel abonnieren

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

Ein Channel, dessen Name kein private-- oder presence--Präfix hat, ist öffentlich: Jeder Client mit dem App-Key kann ihn abonnieren. Behandeln Sie seinen Inhalt daher als lesbar für jeden, der Ihre App öffnen kann.

Private und Presence-Channels

Private- und Presence-Channels werden von Ihrem Backend autorisiert, das das App-Secret hält. Richten Sie den Client auf Ihren Endpunkt: Er sendet {"connection_id", "channel_name"} per POST und erwartet {"auth", "member_data"?} zurück.

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

Übergeben Sie stattdessen eine authorizer-Closure, um über Ihren eigenen Netzwerk-Stack zu signieren.

Eine Ablehnung vom Server (eine ungültige Signatur, eine App über Kapazität) trifft auf der Verbindung statt auf dem Channel ein, weil das Drahtprotokoll keine Channel-Zuordnung enthält. Beobachten Sie diese mit onError. Ein Fehler innerhalb Ihres Authorizers löst bird:subscription_error auf dem Channel aus.

Ein Mitglied anmelden

signin() teilt der Edge mit, zu welchem Mitglied diese Verbindung gehört. Diese Identität ermöglicht es dem API, ein Mitglied zu adressieren oder dessen Verbindungen zu beenden, und sie erfüllt die Anforderung einer App, die autorisierte Verbindungen verlangt.

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

Rufen Sie signin() einmal auf. Die Identität bleibt auf der Verbindung bestehen, sodass der Client sich nach einem Reconnect automatisch erneut anmeldet. Eine fehlgeschlagene automatische Anmeldung hat keinen aktiven Aufruf, aus dem sie werfen kann, deshalb erscheint sie auf onSigninError. Dadurch stört ein fehlerhafter Member-Endpunkt die Channel-Subscriptions nicht.

Verbindungslebenszyklus

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

Die Wiederverbindung erfolgt automatisch, mit exponentiellem Backoff und Full-Jitter von 1 s bis maximal 30 s. Close-Codes im Bereich 4000–4099 sind Ablehnungen und endgültig: Der Client stoppt und meldet den Code, weil eine Ablehnung eine Entscheidung und kein vorübergehender Fehler ist. Codes im Bereich 4200–4299 verbinden sofort neu; alles andere nutzt Backoff. Channels abonnieren sich bei jeder Wiederverbindung mit frischer Autorisierung erneut. Siehe Verbindungslebenszyklus.

Transport ist TLS für jeden Nicht-Loopback-Host. allowInsecure erlaubt ws:// nur für localhost, 127.0.0.1 und [::1], sodass eine aus einem Entwicklungs-Target kopierte Konfiguration den Produktions-Traffic nicht stillschweigend herabstufen kann.

Client-Events

Wenn die Client-Events-Einstellung der App aktiviert ist, kann ein Client, der einen privaten oder Presence-Channel abonniert hat, direkt an seine Peers veröffentlichen:

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

Siehe Client-Events.

Quellcode

github.com/messagebird/bird-sdk-swift, MIT-lizenziert. Melden Sie Probleme dort.