Kotlin SDK

com.messagebird:bird-realtime est le client Kotlin officiel pour Bird Realtime : il maintient un WebSocket vers le edge Bird, s'abonne aux canaux et délivre les événements au fil 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 les clients navigateur et Swift.

C'est une bibliothèque JVM simple, donc le même artefact convient à une application Android comme à un serveur. Les callbacks atterrissent sur le main looper Android quand il existe et s'exécutent en ligne sinon, vous n'avez donc pas besoin d'un build distinct pour chaque cas.

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

Installation

dependencies {
    implementation("com.messagebird:bird-realtime:0.1.0")
}

Sur Android, ajoutez la permission internet à votre manifest. Une bibliothèque n'en contribue plus :

<uses-permission android:name="android.permission.INTERNET" />

Construire un client

import com.messagebird.realtime.BirdRealtime
import com.messagebird.realtime.BirdRealtimeOptions

val bird = BirdRealtime(
    BirdRealtimeOptions(
        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.

Le socket s'ouvre dès la construction du client, vous n'appelez donc pas connect() en premier. connect() et disconnect() servent au cycle de vie de l'application : fermez le socket quand votre activité disparaît et rouvrez-le quand elle revient, et les canaux auxquels vous étiez abonné sont réabonnés automatiquement.

disconnect() laisse le client réutilisable, il conserve donc délibérément le thread worker auquel le client confine son état. Quand vous en avez définitivement fini avec un client, appelez close(), sinon ce thread et le socket vivent aussi longtemps que le processus. La classe est AutoCloseable, donc un bloc use { } s'en charge pour vous. Le client Swift n'a pas besoin d'équivalent : il libère les deux quand la dernière référence disparaît.

S'abonner à un canal

val orders = bird.subscribe("orders")
orders.bind("order-updated") { data ->
    println("order changed: $data")
}

Les payloads arrivent sous forme de kotlinx.serialization.json.JsonElement, lisez-les donc avec l'API de sérialisation plutôt qu'en castant.

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, considérez 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.

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        authEndpoint = "https://your-backend.example.com/bird/auth",
        authHeaders = mapOf("authorization" to "Bearer <session token>"),
    )
)

val room = bird.subscribe("presence-room-42")
if (room is PresenceChannel) {
    room.bind(BirdProtocol.Event.SUBSCRIPTION_SUCCEEDED) {
        println("me: ${room.myId}, members: ${room.members.keys}")
    }
    room.bind(BirdProtocol.Event.MEMBER_ADDED) { member -> println("joined: $member") }
}

Passez un authorizer à la place pour signer via votre propre pile réseau.

Un rejet du serveur (signature invalide, application en surcapacité) arrive sur la connexion et non sur le canal, car le fil ne porte pas d'attribution de canal. Observez-les avec onError. Une erreur à l'intérieur de votre authorizer é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 terminer ses connexions, et c'est ce qui satisfait une application configurée pour exiger des connexions autorisées.

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
        memberAuthEndpoint = "https://your-backend.example.com/bird/auth/member",
    )
)

val me = bird.signin() // suspending
println("signed in as ${me.memberId}")

bird.member.bind("order.shipped") { data ->
    println("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 sign-in automatique échoué n'a pas d'appel actif depuis lequel lever une exception, il apparaît donc sur onSigninError. Cela empêche un endpoint membre défaillant de perturber les abonnements aux canaux.

Cycle de vie de la connexion

bird.onConnectionStateChange { previous, current ->
    println("connection: $previous -> $current")
}
bird.onError { error ->
    if (error.code == 4009) println("session ended elsewhere")
}

La reconnexion est automatique, avec un backoff exponentiel à jitter complet de 1 s jusqu'à un plafond de 30 s. Les codes de fermeture 4000-4099 sont des refus et sont terminaux : le client s'arrête et signale le code, car un refus est une décision et non un échec transitoire. Les codes 4200-4299 déclenchent une reconnexion immédiate ; tout autre code déclenche le 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], de sorte qu'une configuration copiée depuis une cible de développement ne peut pas rétrograder silencieusement le trafic de production.

Événements client

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

room.trigger("client-typing", buildJsonObject { put("on", true) })

Voir événements client.

Source

github.com/messagebird/bird-sdk-kotlin, sous licence MIT. Signalez les problèmes là-bas.