Swift SDK

BirdRealtime est le client Swift officiel pour Bird Realtime : il maintient un WebSocket vers le edge Bird, s'abonne aux canaux et distribue les événements au fur et à mesure de leur publication. Il est écrit à la main plutôt que généré, car Realtime est un plan de données WebSocket et non une surface REST, et il parle le même dialecte filaire que le client navigateur.

Il n'a aucune dépendance (URLSessionWebSocketTask pour le transport, JSONSerialization pour les trames) et fonctionne sur iOS 15+, macOS 12+, tvOS 15+, watchOS 8+ et Linux.

Ce client est le côté réception. La publication d'événements, l'autorisation de canaux et la fermeture de connexions sont des opérations côté serveur sur l'Bird API ; voir publication d'événements.

Installation

Dans Xcode, sélectionnez File > Add Package Dependencies et saisissez l'URL du dépôt. Dans un Package.swift :

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

Ajoutez ensuite le produit à la cible qui l'utilise :

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

Construire un client

import BirdRealtime

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

Seul appKey est requis, plus soit region (us1 ou eu1, qui résout l'hôte edge), soit un wsHost explicite. La clé d'application est publique et livrée dans le code client : elle identifie l'application, elle n'autorise rien. Les handlers s'exécutent sur la file principale sauf si vous passez un deliveryQueue.

S'abonner à un canal

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

Un canal dont le nom n'a pas de préfixe private- ou presence- est public : tout client disposant de la clé d'application peut s'y abonner, traitez donc son contenu comme lisible par quiconque peut ouvrir votre application.

Canaux privés et de présence

Les canaux privés et de présence sont autorisés par votre backend, qui détient le secret de l'application. Dirigez le client vers votre endpoint : il envoie un POST avec {"connection_id", "channel_name"} et attend {"auth", "member_data"?} en retour.

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

Passez plutôt une closure authorizer pour signer via votre propre pile réseau.

Un rejet du serveur (signature invalide, application ayant dépassé sa capacité) arrive sur la connexion et non sur le canal, car le fil ne porte aucune attribution de canal. Observez ces rejets avec onError. Une erreur à l'intérieur de votre autoriseur émet bien bird:subscription_error sur le canal.

Connecter un membre

signin() indique au edge à quel membre cette connexion appartient. Cette identité est ce qui permet au API de s'adresser à un membre ou de fermer ses connexions, et c'est elle qui satisfait une application configurée pour exiger des connexions autorisées.

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

Appelez signin() une seule fois. L'identité reste sur la connexion, le client se reconnecte donc automatiquement après une reconnexion. Un échec de connexion automatique n'a pas d'appel actif depuis lequel lever une exception, il apparaît donc sur onSigninError. Cela évite qu'un endpoint membre défaillant ne perturbe les abonnements aux canaux.

Cycle de vie de la connexion

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

La reconnexion est automatique, avec un backoff exponentiel à gigue complète de 1 s à un plafond de 30 s. Les codes de fermeture 4000–4099 sont des refus définitifs : le client s'arrête et signale le code, car un refus est une décision et non une erreur transitoire. Les codes 4200–4299 déclenchent une reconnexion immédiate ; tout autre code entraîne un backoff. Les canaux se réabonnent avec une autorisation fraîche à chaque reconnexion. Voir cycle de vie de la connexion.

Le transport est TLS pour tout hôte non-loopback. allowInsecure n'autorise ws:// que pour localhost, 127.0.0.1 et [::1], une configuration copiée depuis un environnement de développement ne peut donc pas rétrograder silencieusement le trafic de production.

Événements client

Lorsque le paramètre d'événements client de l'application est activé, un client abonné à un canal privé ou de présence peut publier directement vers ses pairs :

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

Voir événements client.

Source

github.com/messagebird/bird-sdk-swift, licence MIT. Signalez les problèmes sur ce dépôt.