Ikhtisar Realtime
Realtime mengirimkan event ke klien yang terhubung melalui WebSocket. Server Anda mempublikasikan event ke channel bernama, dan klien yang berlangganan menerimanya tanpa polling.
Gunakan Realtime untuk perubahan yang dibutuhkan klien tanpa membuat permintaan tambahan, seperti pembaruan pesanan, pesan chat, perubahan dashboard, atau background job yang selesai.
Channel, member, dan connection
Tiga kata mendeskripsikan modelnya. Ketiganya tidak dapat dipertukarkan.
Channel adalah ruang bernama. Channel ada selama setidaknya satu connection berlangganan, dan hilang ketika yang terakhir meninggalkannya. Nama channel mengizinkan hingga 164 huruf, digit, dan karakter berikut: _ - = @ , . ;.
Connection adalah satu WebSocket terbuka. Connection menerima ID (26896.319537) saat terhubung. Otorisasi menandatangani ID ini, dan publishing dapat mengecualikannya dari pengiriman.
Member adalah identitas terautentikasi pada presence channel. Satu member dapat memiliki beberapa connection, misalnya tiga tab browser. Event presence terpicu saat connection pertama member bergabung dan connection terakhir meninggalkan channel. Tab perantara tidak menghasilkan event tersebut.
Tiga tipe channel
Prefiks nama channel menentukan tipe channel dan perilaku otorisasinya.
| Nama | Siapa yang dapat berlangganan | Memiliki member |
|---|---|---|
| orders | siapa saja yang memiliki app key | tidak |
| private-orders | hanya klien yang ditandatangani backend Anda | tidak |
| presence-lobby | hanya klien yang ditandatangani backend Anda | ya |
Channel public dapat dibaca oleh siapa saja yang memiliki app key, yang disertakan dalam kode klien. Publikasikan hanya data yang boleh dilihat setiap pengunjung. Lihat Public channels.
Channel private meminta backend Anda menyetujui setiap langganan. Klien mengirimkan connection ID dan nama channel ke endpoint Anda, yang mengembalikan signature yang dihitung dengan app secret. Lihat Private channels. Channel private-encrypted-… juga mengenkripsi payload dengan kunci yang disimpan di server Anda. Lihat Encrypted channels.
Channel presence menambahkan identitas ke otorisasi private channel. Setiap pelanggan menerima daftar member dan perubahannya melalui member_id dan opsional member_info. Lihat Presence channels.
Event yang diterima klien
Event aplikasi adalah milik Anda: Anda memilih namanya saat publish (order-updated, message.created) dan mengikat handler ke event tersebut. Selain itu, klien memancarkan ulang event siklus hidup dengan prefiks bird:, yang Anda ikat sama seperti event Anda sendiri:
- bird:subscription_succeeded terpicu satu kali per channel saat langganan aktif. Pada presence channel, event ini membawa daftar member saat ini, sehingga Anda dapat merender ruang sebelum ada yang bergerak.
- bird:member_added dan bird:member_removed terpicu pada presence channel saat member datang dan pergi. member_added terpicu saat connection pertama seseorang berlangganan; member_removed hanya saat connection terakhir mereka pergi. Tab kedua yang dibuka dan ditutup tidak menghasilkan keduanya.
- bird:connection_count melaporkan berapa banyak connection yang berlangganan ke channel, jika aplikasi mengaktifkan penghitungan connection dan event jumlah connection. Event ini menghitung connection, sehingga member dengan tiga tab dihitung tiga.
- bird:subscription_error terpicu saat langganan ditolak, paling sering karena otorisasi gagal.
Nama yang diawali client- dicadangkan untuk event yang dikirim klien langsung satu sama lain, yang merupakan pengaturan aplikasi terpisah dan hanya diizinkan pada private dan presence channel.
Server Anda juga dapat menerima event, sebagai webhook, saat channel menjadi terisi atau kosong dan saat member bergabung atau pergi. Event tersebut tiba sebagai event realtime.* melalui endpoint webhook yang sama dengan Bird lainnya.
Klien
Tiga klien menerima event melalui protokol yang sama. Gunakan @messagebird/realtime untuk browser dan Node.js, BirdRealtime untuk iOS, macOS, dan Linux, atau com.messagebird:bird-realtime untuk Android dan server JVM. Masing-masing mendukung langganan, binding, presence, signin(), dan client event.
Simpan app secret di server Anda. Server SDK menggunakannya untuk mempublikasikan event, mengotorisasi channel, dan memutuskan connection member.
App, key, dan region
App adalah lingkungan terisolasi dengan kredensial dan namespace channel sendiri. Dua app tidak pernah melihat channel satu sama lain, yang menjadikan app sebagai batas yang tepat antara lingkungan staging dan production Anda.
Setiap app menggunakan region permanen yang dipilih saat pembuatan. Gunakan List Realtime regions untuk mengambil identifier yang diterima, dan pilih region yang paling dekat dengan pengguna Anda.
Setiap app memiliki tiga nilai dengan kegunaan berbeda:
- App ID (rap_…) mengidentifikasi app dalam panggilan Bird API dan muncul di setiap path /v1/realtime/apps/….
- Key bersifat publik. Browser terhubung menggunakannya, dan aman untuk disertakan dalam kode klien.
- Secret dipasangkan dengan key untuk mengautentikasi panggilan sisi server dan menandatangani otorisasi channel. Secret ditampilkan satu kali, saat pembuatan. Siapa pun yang memilikinya dapat mempublikasikan ke app Anda dan memalsukan identitas presence.
Kelola app dan rotasi key di halaman Realtime apps. Buat key kedua, deploy, lalu cabut key lama.
Visibilitas
Halaman Realtime metrics melaporkan tiga nilai per app atau lintas workspace untuk jendela waktu yang Anda pilih:
- Max connections adalah jumlah connection terbuka tertinggi pada saat yang sama dalam jendela waktu tersebut. Puncak ini adalah nilai yang digunakan untuk menerapkan batas connection.
- Average connections adalah rata-rata dari puncak harian. Nilai ini tidak merata-ratakan setiap sampel. Workspace yang melonjak setiap sore dan idle semalaman menunjukkan rata-rata jauh di atas jam-jam tenangnya.
- Messages menghitung pengiriman event, satu per channel: publish yang menyebutkan 50 channel dihitung sebagai 50. Nilai ini juga mencakup event yang dikirim protokol atas nama Anda, sehingga presence join dan pembaruan jumlah connection masuk ke angka yang sama, itulah mengapa nilainya bisa lebih tinggi dari publish yang dibuat kode Anda.
Penggunaan diagregasi dalam bucket satu menit, sehingga lalu lintas terbaru dapat memerlukan beberapa menit untuk muncul. API penggunaan saat ini hanya tersedia di dashboard. Untuk visibilitas secara programatik, catat publish di sistem Anda atau derivasikan aktivitas dari webhook realtime.*.
Paket dan batas
Paket gratis mencakup 100 connection bersamaan dan 200.000 pesan per hari, di seluruh app dalam workspace. Membuat lebih banyak app tidak menaikkan batas tersebut, karena batas berlaku untuk workspace.
Paket berbayar mulai dari $25 per bulan untuk 250 connection bersamaan dan 500.000 pesan per hari, dan meningkat hingga 30.000 connection dan 90 juta pesan per hari. Realtime pricing mencantumkan setiap tingkatnya.
Batas per permintaan berlaku di setiap paket: satu publish menyebutkan maksimal 100 channel, satu batch membawa maksimal 10 event, dan payload event dibatasi 10 KB setelah serialisasi.
Langkah selanjutnya
- Kirim event realtime pertama Anda memandu seluruh alur dari awal hingga akhir.
- Publishing events membahas publishing dari server Anda, batching, dan mengecualikan klien pengirim.
- Authorizing channels adalah kontrak yang diimplementasikan backend Anda untuk private dan presence channel.
Sumber daya terkait
Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini. Sumber daya tersedia dalam bahasa Inggris.