Swift SDK

BirdRealtime is de officiële Swift-client voor Bird Realtime: hij houdt een WebSocket open naar de Bird-edge, abonneert zich op kanalen en levert events af zodra ze worden gepubliceerd. Hij is met de hand geschreven in plaats van gegenereerd, omdat Realtime een WebSocket-datavlak is en geen REST-oppervlak, en hij spreekt hetzelfde draadprotocol als de browserclient.

Hij heeft geen dependencies (URLSessionWebSocketTask voor transport, JSONSerialization voor frames) en draait op iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ en Linux.

Deze client is de ontvangende kant. Events publiceren, kanalen autoriseren en verbindingen beëindigen zijn server-side operaties op de Bird API; zie events publiceren.

Installeren

Selecteer in Xcode File > Add Package Dependencies en voer de repository-URL in. In een Package.swift:

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

Voeg het product vervolgens toe aan het target dat het gebruikt:

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

Een client aanmaken

import BirdRealtime

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

Alleen appKey is vereist, plus ofwel region (us1 of eu1, die de edge-host oplost) of een expliciete wsHost. De app key is publiek en zit in de clientcode: hij identificeert de app, hij autoriseert niets. Handlers draaien op de main queue, tenzij je een deliveryQueue meegeeft.

Abonneren op een kanaal

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

Een kanaal waarvan de naam geen private-- of presence--prefix heeft, is publiek: elke client met de app key kan zich abonneren, dus beschouw de inhoud als leesbaar voor iedereen die je app kan openen.

Private en presence-kanalen

Private en presence-kanalen worden geautoriseerd door je backend, die het app secret bewaart. Wijs de client naar je endpoint: hij stuurt {"connection_id", "channel_name"} via een POST-verzoek en verwacht {"auth", "member_data"?} terug.

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

Geef in plaats daarvan een authorizer-closure mee om via je eigen netwerkstack te ondertekenen.

Een afwijzing van de server (een ongeldige handtekening, een app die over capaciteit zit) komt binnen op de verbinding in plaats van op het kanaal, omdat het draadprotocol geen kanaaltoewijzing meestuurt. Observeer die met onError. Een fout binnen je authorizer zendt wel bird:subscription_error uit op het kanaal.

Een lid aanmelden

signin() vertelt de edge bij welk lid deze verbinding hoort. Met die identiteit kan de API een lid adresseren of de verbindingen van dat lid beëindigen, en die identiteit voldoet aan een app die is geconfigureerd om geautoriseerde verbindingen te vereisen.

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

Roep signin() één keer aan. De identiteit blijft op de verbinding, dus de client meldt zich na een herverbinding automatisch opnieuw aan. Bij een mislukte automatische aanmelding is er geen actieve aanroep die de fout kan gooien, dus verschijnt de fout op onSigninError. Zo verstoort een falend member-endpoint geen kanaalabonnementen.

Verbindingslevenscyclus

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

Herverbinding is automatisch, met full-jitter exponentiële backoff van 1 s tot een maximum van 30 s. Close codes in 4000–4099 zijn weigeringen en definitief: de client stopt en rapporteert de code, omdat een weigering een beslissing is en geen tijdelijke fout. Codes in 4200–4299 herverbinden direct; al het andere doet backoff. Kanalen herabonneren zich met verse autorisatie bij elke herverbinding. Zie verbindingslevenscyclus.

Transport is TLS voor elke niet-loopback-host. allowInsecure staat ws:// alleen toe voor localhost, 127.0.0.1 en [::1], dus een config gekopieerd van een ontwikkeldoel kan productieverkeer niet stilzwijgend downgraden.

Client events

Als de client-events-instelling van de app is ingeschakeld, kan een client die is geabonneerd op een private of presence-kanaal rechtstreeks naar zijn peers publiceren:

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

Zie client events.

Bron

github.com/messagebird/bird-sdk-swift, MIT-licentie. Meld problemen daar.