Channel Realtime

Channel adalah sebuah nama. Tidak perlu provisioning.

Channel ada begitu sesuatu berlangganan padanya dan menghilang saat koneksi terakhir pergi. Namanya menentukan tipe: public untuk apa pun yang boleh dibaca pengunjung, private untuk apa pun yang dibatasi per pelanggan, presence untuk ruang dengan daftar anggota, dan awalan cache untuk state yang langsung dibutuhkan oleh subscriber yang baru bergabung.

channels.ts

4 subscribed

const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" });

// Public: anyone holding the app key can subscribe.
const scores = bird.subscribe("match-42");

// Private: your backend signs every subscription.
const order = bird.subscribe("private-order-ord_123");

// Presence: private, plus an identity the room can see.
const room = bird.subscribe("presence-room-42");

// Cache: the latest event replays to whoever joins next.
const build = bird.subscribe("cache-build-8821");

build.bind("bird:cache_miss", () => showSkeleton());

channels.ts

4 subscribed

const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" });

// Public: anyone holding the app key can subscribe.
const scores = bird.subscribe("match-42");

// Private: your backend signs every subscription.
const order = bird.subscribe("private-order-ord_123");

// Presence: private, plus an identity the room can see.
const room = bird.subscribe("presence-room-42");

// Cache: the latest event replays to whoever joins next.
const build = bird.subscribe("cache-build-8821");

build.bind("bird:cache_miss", () => showSkeleton());

Awalan adalah konfigurasinya.

Tidak ada registri channel yang perlu disinkronkan.

Channel adalah model pengalamatan dari Bird Realtime API. Anda tidak perlu membuatnya: Anda berlangganan ke sebuah nama, dan tiga karakter pertama dari nama tersebut memberi tahu edge cara memperlakukannya. Nama tanpa awalan bersifat public. private- meminta backend Anda menyetujui setiap langganan. presence- melakukan hal yang sama dan melampirkan identitas. private-encrypted- menyegel payload dengan kunci yang tidak pernah dimiliki Bird. Nama bisa hingga 164 karakter, bersifat case-sensitive, dan merupakan satu-satunya bagian dari channel yang harus Anda pikirkan dengan cermat, karena nama public terlihat oleh siapa pun yang memegang app key.

Lima jenis ruang.

Protokol sama, client sama, panggilan publish sama. Namanya yang berbeda.

01
Channel public.
Tanpa endpoint otorisasi, tanpa registrasi. Siapa pun yang memegang app key dapat berlangganan, menjadikannya cocok untuk hasil build, skor langsung, informasi penerbangan, atau halaman status, dan tidak cocok untuk apa pun yang dibatasi per pelanggan. Jangan masukkan identifier ke dalam nama: orders tidak mengungkapkan apa pun, orders-user-4821 mengungkapkan bahwa user 4821 ada.
02
Channel private.
Nama private- merutekan langganan melalui endpoint Anda sendiri, yang memeriksa sesi dan menandatangani connection id serta nama channel dengan app secret. Aturan Anda, sesi Anda, 403 Anda. Edge memverifikasi tanda tangan dan tidak ada yang lain masuk ke channel.
03
Channel presence.
Otorisasi private-channel ditambah identitas, sehingga setiap subscriber mendapatkan daftar anggota dan mendengar tentang kedatangan serta kepergian. Ini satu-satunya tipe channel dengan roster.
04
Channel encrypted.
Channel private-encrypted- membawa payload yang disegel server Anda dengan master key 32-byte yang tidak pernah muncul dalam permintaan Realtime. Edge dan semua yang ada di antaranya dengan browser melihat ciphertext. Nama channel dan event tetap dalam teks biasa, jadi pilih nama yang tidak membocorkan apa yang Anda lindungi.
05
Channel cache.
Awali nama dengan cache-, setelah awalan tipe apa pun, dan channel mengingat event terbaru yang dipublikasikan via API lalu memutarnya ulang ke setiap subscriber baru. Langganan sekaligus berfungsi sebagai pengambilan state awal. Dua batasan yang perlu dipertimbangkan dalam desain: hanya event terbaru yang disimpan, dan mungkin kedaluwarsa sebelum batas 30 menit, jadi masukkan seluruh state di setiap payload dan isi ulang dari webhook cache-miss daripada mengasumsikan cache selalu terisi.

Satu publish, hingga seratus channel.

Publishing adalah panggilan REST biasa dari server Anda. Sebutkan hingga 100 channel dalam satu permintaan dan edge menyebarkan event ke semuanya. Satu batch membawa hingga 10 event yang tidak terkait, masing-masing ke channelnya sendiri. Kirim connection id client yang bertindak sebagai exclude_connection_id dan tab yang sudah menerapkan perubahan secara lokal akan dilewati. Minta jumlah koneksi atau anggota dengan include dan respons memberi tahu Anda state setiap channel saat publish. Coba ulang dengan idempotency key yang sama dan Anda tidak akan mengirim dua kali.

publish.ts

200 · accepted

// One event, up to 100 channels, one request.
const result = await bird.realtime.publish(APP_ID, {
  event: "score-updated",
  channels: ["match-42", "cache-match-42"],
  data: { home: 2, away: 1 },
  // The tab that scored already rendered it locally.
  exclude_connection_id: "26896.319537",
  include: ["connection_count"],
});

for (const channel of result.data ?? []) {
  console.log(channel.name, channel.connection_count);
}

Client dapat berbicara satu sama lain secara langsung.

Indikator mengetik atau posisi kursor tidak perlu mengunjungi API Anda. Aktifkan client event pada app dan client yang berlangganan dapat memicu event bernama client-something langsung ke yang lain di channel, dibatasi 10 per detik per koneksi. Ini hanya berfungsi di channel private dan presence, dan itu disengaja: app key dikirim di halaman Anda, jadi otorisasi yang membuat client cukup tepercaya untuk broadcast. Perlakukan yang datang sebagai sinyal, bukan sebagai state otoritatif, karena edge tidak memvalidasi payload.

Apa yang akan dan tidak akan diingat channel.

Publish mengembalikan respons begitu edge menerima event. Pengiriman bersifat asinkron, tidak ada tanda terima per client, dan client yang terputus di tengah pengiriman tidak akan dikirim ulang event tersebut saat reconnect. Itulah kontrak yang jujur, dan itulah mengapa state yang tahan lama seharusnya ada di database Anda dan event mengumumkan bahwa state tersebut berubah. Batas sama di setiap paket: 100 channel per publish, 10 event per batch, 10 KB per payload, nama channel 164 karakter.

Pelajari lebih dalam di dokumentasi.

Ringkasan Realtime mendefinisikan channel, anggota, dan koneksi dalam satu halaman. Publishing event membahas broadcast, batch, dan pengecualian, channel cache menjelaskan replay, dan query state channel adalah pembacaan sisi server untuk occupancy dan jumlah.