Kotlin SDK

com.messagebird:bird-realtime adalah klien Kotlin resmi untuk Bird Realtime: ia mempertahankan koneksi WebSocket ke edge Bird, subscribe ke channel, dan mengirimkan event saat dipublikasikan. Klien ini ditulis manual, bukan di-generate, karena Realtime adalah data plane WebSocket, bukan surface REST, dan ia menggunakan dialek wire yang sama dengan klien browser dan Swift.

Ini adalah library JVM biasa, sehingga artefak yang sama dapat digunakan untuk aplikasi Android maupun server. Callback mendarat di main looper Android jika ada, dan berjalan inline jika tidak, sehingga Anda tidak perlu build terpisah untuk masing-masing.

Klien ini adalah sisi penerima. Mempublikasikan event, mengotorisasi channel, dan memutus koneksi adalah operasi sisi server pada Bird API; lihat mempublikasikan event.

Instal

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

Di Android, tambahkan izin internet ke manifest Anda. Library tidak lagi menyertakannya:

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

Membuat klien

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

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

Hanya appKey yang wajib, ditambah region (us1 atau eu1, yang me-resolve host edge) atau wsHost eksplisit. App key bersifat publik dan disertakan dalam kode klien: ia mengidentifikasi aplikasi, bukan mengotorisasi apa pun.

Socket terbuka saat klien dibuat, jadi Anda tidak perlu memanggil connect() terlebih dahulu. connect() dan disconnect() ditujukan untuk lifecycle aplikasi: tutup socket saat activity Anda hilang dan buka kembali saat kembali, dan channel yang Anda subscribe akan di-subscribe ulang secara otomatis.

disconnect() membiarkan klien tetap dapat digunakan kembali, sehingga sengaja mempertahankan worker thread tempat klien membatasi state-nya. Jika Anda sudah selesai sepenuhnya dengan sebuah klien, close() klien tersebut, atau thread dan socket itu akan hidup selama proses berjalan. Class ini adalah AutoCloseable, sehingga blok use { } menanganinya untuk Anda. Klien Swift tidak memerlukan padanannya: ia melepaskan keduanya saat referensi terakhir hilang.

Subscribe ke channel

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

Payload tiba sebagai kotlinx.serialization.json.JsonElement, jadi baca dengan API serialisasi, bukan dengan casting.

Channel yang namanya tidak memiliki prefiks private- atau presence- adalah publik: klien mana pun dengan app key dapat subscribe, jadi perlakukan isinya sebagai dapat dibaca oleh siapa saja yang dapat membuka aplikasi Anda.

Channel private dan presence

Channel private dan presence diotorisasi oleh backend Anda, yang menyimpan app secret. Arahkan klien ke endpoint Anda: ia melakukan POST {"connection_id", "channel_name"} dan mengharapkan {"auth", "member_data"?} sebagai respons.

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

Berikan authorizer sebagai gantinya untuk melakukan sign melalui networking stack Anda sendiri.

Penolakan dari server (signature tidak valid, aplikasi melebihi kapasitas) tiba di koneksi, bukan di channel, karena wire tidak membawa atribusi channel. Pantau hal tersebut dengan onError. Kegagalan di dalam authorizer Anda memang mengirimkan bird:subscription_error di channel.

Sign in member

signin() memberi tahu edge member mana yang dimiliki koneksi ini. Identitas itulah yang memungkinkan API menyapa member atau memutus koneksi mereka, dan memenuhi syarat aplikasi yang dikonfigurasi untuk mewajibkan koneksi terotorisasi.

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

Panggil signin() sekali. Identitas tetap ada di koneksi, sehingga klien sign in ulang secara otomatis setelah reconnect. Sign-in otomatis yang gagal tidak memiliki panggilan aktif untuk melempar exception, sehingga muncul di onSigninError. Ini mencegah endpoint member yang bermasalah mengganggu subscription channel.

Lifecycle koneksi

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

Reconnect berjalan otomatis, dengan exponential backoff full-jitter dari 1 detik hingga batas 30 detik. Close code 4000–4099 adalah penolakan dan bersifat terminal: klien berhenti dan melaporkan kode tersebut, karena penolakan adalah keputusan, bukan kegagalan sementara. Kode 4200–4299 langsung reconnect; selainnya menggunakan backoff. Channel di-subscribe ulang dengan otorisasi baru pada setiap reconnect. Lihat lifecycle koneksi.

Transport menggunakan TLS untuk setiap host non-loopback. allowInsecure mengizinkan ws:// hanya untuk localhost, 127.0.0.1, dan [::1], sehingga konfigurasi yang disalin dari target development tidak dapat secara diam-diam menurunkan traffic production.

Client event

Dengan pengaturan client-events aplikasi diaktifkan, klien yang subscribe ke channel private atau presence dapat mempublikasikan langsung ke peer-nya:

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

Lihat client event.

Sumber

github.com/messagebird/bird-sdk-kotlin, berlisensi MIT. Laporkan masalah di sana.