Przegląd Realtime
Realtime wysyła zdarzenia do podłączonych klientów przez WebSockety. Twój serwer publikuje zdarzenie na nazwanym kanale, a subskrybujący klienci odbierają je bez odpytywania.
Używaj Realtime do zmian, które klient powinien otrzymać bez wysyłania kolejnego żądania, takich jak aktualizacje zamówień, wiadomości czatu, zmiany na dashboardzie czy ukończone zadania w tle.
Kanały, członkowie i połączenia
Trzy słowa opisują model. Nie są wymienne.
Kanał (channel) to nazwany pokój. Istnieje, dopóki przynajmniej jedno połączenie go subskrybuje, i znika, gdy ostatnie się rozłączy. Nazwy kanałów mogą zawierać do 164 liter, cyfr i następujących znaków: _ - = @ , . ;.
Połączenie (connection) to jeden otwarty WebSocket. Przy nawiązaniu otrzymuje identyfikator (26896.319537). Autoryzacja podpisuje ten identyfikator, a publikacja może wykluczyć go z dostarczania.
Członek (member) to uwierzytelniona tożsamość na kanale presence. Jeden członek może mieć kilka połączeń, na przykład trzy karty przeglądarki. Zdarzenia presence są emitowane, gdy pierwsze połączenie członka dołącza i gdy ostatnie się rozłącza. Pośrednie karty ich nie generują.
Trzy typy kanałów
Prefiks nazwy kanału określa typ kanału i sposób autoryzacji.
| Nazwa | Kto może subskrybować | Ma członków |
|---|---|---|
| orders | każdy posiadacz klucza aplikacji | nie |
| private-orders | tylko klienci podpisani przez Twój backend | nie |
| presence-lobby | tylko klienci podpisani przez Twój backend | tak |
Kanał public jest dostępny do odczytu dla każdego, kto ma klucz aplikacji, a ten klucz trafia do kodu klienta. Publikuj tylko dane, które może zobaczyć każdy odwiedzający. Zobacz Kanały publiczne.
Kanał private wymaga od Twojego backendu zatwierdzenia każdej subskrypcji. Klient wysyła identyfikator połączenia i nazwę kanału na Twój endpoint, który zwraca podpis obliczony przy użyciu sekretu aplikacji. Zobacz Kanały prywatne. Kanał private-encrypted-… dodatkowo szyfruje payloady kluczem przechowywanym na Twoich serwerach. Zobacz Kanały szyfrowane.
Kanał presence dodaje tożsamość do autoryzacji kanału prywatnego. Każdy subskrybent otrzymuje listę członków i zmiany przez member_id oraz opcjonalnie member_info. Zobacz Kanały presence.
Zdarzenia odbierane przez klienta
Zdarzenia aplikacji należą do Ciebie: wybierasz nazwę w momencie publikacji (order-updated, message.created) i przypisujesz do niej handler. Oprócz nich klient reemituje zdarzenia cyklu życia z prefiksem bird:, które przypisujesz dokładnie tak samo jak własne:
- bird:subscription_succeeded jest emitowane raz na kanał, gdy subskrypcja jest aktywna. Na kanale presence zawiera bieżącą listę członków, więc możesz wyrenderować pokój, zanim ktokolwiek się poruszy.
- bird:member_added i bird:member_removed są emitowane na kanałach presence, gdy członkowie dołączają i odchodzą. member_added jest emitowane, gdy pierwsze połączenie osoby subskrybuje; member_removed tylko gdy ostatnie się rozłącza. Otwarcie i zamknięcie drugiej karty nie generuje żadnego z nich.
- bird:connection_count podaje liczbę połączeń subskrybujących kanał, jeśli aplikacja ma włączone zliczanie połączeń i zdarzenia licznika połączeń. Zlicza połączenia, więc członek z trzema kartami liczy się jako trzy.
- bird:subscription_error jest emitowane, gdy subskrypcja zostanie odrzucona, najczęściej z powodu nieudanej autoryzacji.
Nazwy zaczynające się od client- są zarezerwowane dla zdarzeń wysyłanych bezpośrednio między klientami. To osobne ustawienie aplikacji, dozwolone tylko na kanałach prywatnych i presence.
Twój serwer również może odbierać zdarzenia jako webhooki, gdy kanał staje się zajęty lub pusty i gdy członkowie dołączają lub odchodzą. Docierają one jako zdarzenia realtime.* przez te same endpointy webhooków co reszta Bird.
Klienty
Trzy klienty odbierają zdarzenia przez ten sam protokół. Użyj @messagebird/realtime dla przeglądarek i Node.js, BirdRealtime dla iOS, macOS i Linuksa lub com.messagebird:bird-realtime dla Androida i serwerowej JVM. Każdy obsługuje subskrypcje, bindowania, presence, signin() i zdarzenia klienckie.
Przechowuj sekret aplikacji na swoim serwerze. SDK serwerowe używają go do publikowania zdarzeń, autoryzowania kanałów i rozłączania członków.
Aplikacje, klucze i regiony
Aplikacja to izolowane środowisko z własnymi poświadczeniami i własną przestrzenią nazw kanałów. Dwie aplikacje nigdy nie widzą swoich kanałów nawzajem, dlatego aplikacja jest właściwą granicą między środowiskiem stagingowym a produkcyjnym.
Każda aplikacja używa niezmiennego regionu wybranego przy tworzeniu. Użyj Wyświetl regiony Realtime, aby pobrać akceptowane identyfikatory, i wybierz region najbliższy Twoim użytkownikom.
Każda aplikacja ma trzy wartości o różnym przeznaczeniu:
- App ID (rap_…) identyfikuje aplikację w wywołaniach Bird API i pojawia się w każdej ścieżce /v1/realtime/apps/….
- Klucz jest publiczny. Przeglądarki łączą się za jego pomocą i można go bezpiecznie umieszczać w kodzie klienta.
- Sekret jest parowany z kluczem w celu uwierzytelniania wywołań po stronie serwera i podpisywania autoryzacji kanałów. Jest wyświetlany tylko raz, przy tworzeniu. Każdy, kto go posiada, może publikować w Twojej aplikacji i fałszować tożsamości presence.
Zarządzaj aplikacjami i rotuj klucze na stronie Aplikacje Realtime. Utwórz drugi klucz, wdróż go, a następnie unieważnij stary.
Widoczność
Strona Metryki Realtime podaje trzy wartości na aplikację lub dla całego obszaru roboczego w wybranym oknie czasowym:
- Maks. połączeń to najwyższa liczba połączeń otwartych jednocześnie w danym oknie. Ten szczyt to wartość, do której stosuje się limit połączeń.
- Średnia połączeń to średnia dziennych szczytów. Nie uśrednia każdej próbki. Obszar roboczy, który ma szczyty każdego popołudnia i jest bezczynny nocą, wykazuje średnią znacznie powyżej wartości z cichych godzin.
- Wiadomości zliczają dostarczenia zdarzeń, po jednym na kanał: publikacja wskazująca 50 kanałów liczy się jako 50. Uwzględnia też zdarzenia wysyłane przez protokół w Twoim imieniu, więc dołączenia presence i aktualizacje licznika połączeń trafiają do tej samej liczby. Dlatego może ona wyprzedzać liczbę publikacji wykonanych przez Twój kod.
Zużycie jest agregowane w jednominutowych przedziałach, więc ostatni ruch może pojawić się z kilkuminutowym opóźnieniem. API zużycia jest obecnie dostępne tylko w dashboardzie. Aby uzyskać programistyczny wgląd, rejestruj publikacje w swoich systemach lub wywodź aktywność z webhooków realtime.*.
Plany i limity
Darmowy plan obejmuje 100 jednoczesnych połączeń i 200 000 wiadomości dziennie dla wszystkich aplikacji w obszarze roboczym. Tworzenie kolejnych aplikacji nie podnosi limitu, ponieważ dotyczy on obszaru roboczego.
Płatne plany zaczynają się od 25 $ miesięcznie za 250 jednoczesnych połączeń i 500 000 wiadomości dziennie i skalują się do 30 000 połączeń i 90 milionów wiadomości dziennie. Cennik Realtime zawiera listę wszystkich progów.
Limity na żądanie obowiązują w każdym planie: jedna publikacja wskazuje najwyżej 100 kanałów, batch zawiera najwyżej 10 zdarzeń, a payload zdarzenia jest ograniczony do 10 KB po serializacji.
Następne kroki
- Wyślij swoje pierwsze zdarzenie Realtime przeprowadza przez cały obieg od początku do końca.
- Publikowanie zdarzeń obejmuje publikowanie z serwera, batchowanie i wykluczanie klienta źródłowego.
- Autoryzacja kanałów to kontrakt, który Twój backend implementuje dla kanałów prywatnych i presence.
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.