Kanały Realtime

Kanał to nazwa. Nic do konfiguracji.

Zacznij Przeczytaj przewodnik po kanałach

Kanał istnieje od momentu, gdy coś go zasubskrybuje, i znika, gdy ostatnie połączenie się rozłączy. Jego nazwa określa typ: publiczny — dla treści dostępnych każdemu odwiedzającemu, prywatny — dla danych przypisanych do klienta, obecności — dla pokoju z listą uczestników, a prefiks cache — dla stanu, który spóźniony uczestnik potrzebuje natychmiast.

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());

Prefiks to konfiguracja.

Nie ma rejestru kanałów, który trzeba synchronizować.

Kanały to model adresowania Bird Realtime API. Nigdy nie tworzysz kanału: subskrybujesz nazwę, a pierwsze trzy znaki tej nazwy mówią serwerowi brzegowemu, jak ją traktować. Nazwa bez prefiksu jest publiczna. private- wymaga od Twojego backendu zatwierdzenia każdej subskrypcji. presence- robi to samo i dołącza tożsamość. private-encrypted- szyfruje dane kluczem, którego Bird nigdy nie posiada. Nazwy mogą mieć do 164 znaków, rozróżniają wielkość liter i są jedyną częścią kanału, nad którą warto się dobrze zastanowić, ponieważ publiczna nazwa jest widoczna dla każdego, kto posiada klucz aplikacji.

Pięć rodzajów pokojów.

Ten sam protokół, ten sam klient, to samo wywołanie publish. Różni się tylko nazwa.

01
Kanały publiczne.
Bez endpointu autoryzacji, bez rejestracji. Każdy, kto posiada klucz aplikacji, może subskrybować — co sprawia, że nadają się do wyników buildów, wyników na żywo, informacji o lotach czy strony statusu, ale nie do danych przypisanych do jednego klienta. Nie umieszczaj identyfikatorów w nazwie: orders nie zdradza niczego, orders-user-4821 ujawnia, że użytkownik 4821 istnieje.
02
Kanały prywatne.
Nazwa z prefiksem private- kieruje subskrypcję przez Twój własny endpoint, który sprawdza sesję i podpisuje identyfikator połączenia oraz nazwę kanału sekretem aplikacji. Twoje reguły, Twoja sesja, Twój 403. Serwer brzegowy weryfikuje podpis i nic innego nie dociera do kanału.
03
Kanały obecności.
Autoryzacja kanału prywatnego plus tożsamość — dzięki czemu każdy subskrybent otrzymuje listę członków i jest informowany o dołączeniach i odejściach. To jedyny typ kanału z listą uczestników.
04
Kanały szyfrowane.
Kanał private-encrypted- przesyła dane zaszyfrowane przez Twój serwer 32-bajtowym kluczem głównym, który nigdy nie pojawia się w żądaniu Realtime. Serwer brzegowy i wszystko pomiędzy nim a przeglądarką widzi szyfrogram. Nazwy kanałów i zdarzeń pozostają jawne, więc wybieraj nazwy, które nie zdradzają, co chronisz.
05
Kanały z cache.
Rozpocznij nazwę od cache-, po dowolnym prefiksie typu, a kanał zapamięta ostatnie zdarzenie opublikowane przez API i odtworzy je każdemu nowemu subskrybentowi. Subskrypcja pełni jednocześnie rolę początkowego pobrania stanu. Dwa ograniczenia warte uwzględnienia w projekcie: przechowywane jest tylko najnowsze zdarzenie i może wygasnąć przed upływem 30-minutowego limitu — dlatego umieszczaj cały stan w każdym payloadzie i uzupełniaj dane z webhooka cache-miss, zamiast zakładać, że cache jest aktualny.

Jeden publish, do stu kanałów.

Publikowanie to zwykłe wywołanie REST z Twojego serwera. Wskaż do 100 kanałów w jednym żądaniu, a serwer brzegowy rozśle zdarzenie do nich wszystkich. Batch mieści do 10 niezależnych zdarzeń, każde do własnego kanału. Przekaż identyfikator połączenia działającego klienta jako exclude_connection_id, a karta, która już lokalnie zastosowała zmianę, zostanie pominięta. Poproś o liczbę połączeń lub członków za pomocą include, a odpowiedź poda stan każdego kanału w momencie publikacji. Powtórz żądanie z tym samym kluczem idempotentności, a zdarzenie nie zostanie dostarczone dwukrotnie.

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

Klienci mogą komunikować się ze sobą bezpośrednio.

Wskaźnik pisania czy pozycja kursora nie muszą trafiać do Twojego API. Włącz zdarzenia klienckie w aplikacji, a zasubskrybowany klient może wywołać zdarzenie o nazwie client-coś bezpośrednio do pozostałych uczestników kanału — z limitem 10 na sekundę na połączenie. Działają tylko na kanałach prywatnych i obecności, co jest celowe: klucz aplikacji jest osadzony w Twojej stronie, więc autoryzacja decyduje o tym, czy klient jest wystarczająco wiarygodny, by nadawać. Traktuj to, co przychodzi, jako sygnał, nigdy jako autorytatywny stan, ponieważ serwer brzegowy nie waliduje payloadu.

Co kanał zapamięta, a czego nie.

Publish zwraca odpowiedź, gdy serwer brzegowy zaakceptuje zdarzenie. Dostarczanie jest asynchroniczne, nie ma potwierdzenia per klient, a klient, który rozłączy się w trakcie dostarczania, nie otrzyma zdarzenia ponownie po reconnect. Taki jest uczciwy kontrakt i dlatego trwały stan powinien być w Twojej bazie danych, a zdarzenia informują, że się zmienił. Limity są takie same w każdym planie: 100 kanałów na publish, 10 zdarzeń na batch, 10 KB na payload, nazwy kanałów do 164 znaków.

Więcej szczegółów w dokumentacji.

Przegląd Realtime definiuje kanały, członków i połączenia na jednej stronie. Publikowanie zdarzeń obejmuje broadcast, batch i wykluczanie, kanały z cache wyjaśniają mechanizm odtwarzania, a odpytywanie stanu kanału to odczyt po stronie serwera dla zajętości i liczników.