Kotlin SDK

com.messagebird:bird-realtime ist der offizielle Kotlin-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 ist und keine REST-Oberfläche, und er spricht denselben Drahtdialekt wie die Browser- und Swift-Clients.

Es ist eine reine JVM-Bibliothek, daher funktioniert dasselbe Artefakt sowohl in einer Android-App als auch auf einem Server. Callbacks landen auf dem Android-Main-Looper, wenn einer existiert, und laufen andernfalls inline, sodass Sie keinen separaten Build für jede Plattform benötigen.

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.

Installieren

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

Fügen Sie unter Android die Internet-Berechtigung zu Ihrem Manifest hinzu. Eine Bibliothek steuert keine mehr bei:

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

Client erstellen

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

val bird = BirdRealtime(
    BirdRealtimeOptions(
        appKey = "your-app-key",
        region = "us1",
    )
)

Nur appKey ist erforderlich, plus 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, er autorisiert nichts.

Der Socket öffnet sich beim Erstellen des Clients, Sie rufen also nicht zuerst connect() auf. connect() und disconnect() sind für den App-Lebenszyklus gedacht: Schließen Sie den Socket, wenn Ihre Activity verschwindet, und öffnen Sie ihn wieder, wenn sie zurückkehrt. Die von Ihnen abonnierten Channels werden dabei automatisch erneut abonniert.

disconnect() lässt den Client wiederverwendbar, behält also bewusst den Worker-Thread bei, auf den der Client seinen Zustand beschränkt. Wenn Sie einen Client endgültig nicht mehr benötigen, rufen Sie close() auf, sonst leben dieser Thread und der Socket so lange wie der Prozess. Die Klasse ist AutoCloseable, ein use { }-Block erledigt das also für Sie. Der Swift-Client braucht kein Äquivalent: Er gibt beides frei, wenn die letzte Referenz verschwindet.

Einen Channel abonnieren

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

Payloads kommen als kotlinx.serialization.json.JsonElement an. Lesen Sie sie mit der Serialisierungs-API, statt sie zu casten.

Ein Channel, dessen Name kein private-- oder presence--Präfix hat, ist öffentlich: Jeder Client mit dem App-Key kann ihn abonnieren. Betrachten 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. Verweisen Sie den Client auf Ihren Endpunkt: Er sendet {"connection_id", "channel_name"} per POST und erwartet {"auth", "member_data"?} zurück.

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

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

Eine Ablehnung vom Server (eine ungültige Signatur, eine App über Kapazität) kommt auf der Verbindung an statt auf dem Channel, weil der Draht keine Channel-Zuordnung mitführt. Beobachten Sie diese mit onError. Ein Fehler innerhalb Ihres Authorizers gibt bird:subscription_error auf dem Channel aus.

Ein Mitglied anmelden

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

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

Rufen Sie signin() einmal auf. Die Identität bleibt auf der Verbindung bestehen, der Client meldet sich nach einem Reconnect also automatisch erneut an. Eine fehlgeschlagene automatische Anmeldung hat keinen aktiven Aufruf, von dem sie werfen könnte, und erscheint daher auf onSigninError. So stört ein fehlerhafter Member-Endpunkt die Channel-Abonnements nicht.

Verbindungslebenszyklus

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

Die Wiederverbindung erfolgt automatisch, mit Full-Jitter-exponentiellem Backoff von 1 s bis zu einer Obergrenze von 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 ist und kein vorübergehender Fehler. Codes im Bereich 4200–4299 verbinden sofort neu; alles andere löst Backoff aus. Channels werden bei jedem Reconnect mit frischer Autorisierung erneut abonniert. Siehe Verbindungslebenszyklus.

Der 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 Entwicklungsziel kopierte Konfiguration den Produktionsdatenverkehr 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 senden:

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

Siehe Client-Events.

Quellcode

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