Aktualizacja zamówienia może mieć dwóch konsumentów: Twoją bazę danych i klienta obserwującego stronę zamówienia. Potrzebują oni różnego zachowania odzyskiwania po zerwaniu połączenia.
Twoja baza danych potrzebuje trwałego zapisu zdarzenia. Strona klienta może potrzebować jedynie najnowszego stanu zamówienia po ponownym połączeniu.
Jakie są cztery opcje?
Bird oferuje webhooki, Realtime, strumień zdarzeń dashboardu oraz odczyty API, które możesz odpytywać.
Użyj webhooków, aby odbierać zdarzenia na swoim serwerze. Użyj Realtime, aby aktualizować podłączonych klientów. Strumień SSE wysyła zmiany zasobów do sesji dashboardu. Polling pozwala aplikacji odczytywać stan zasobów według harmonogramu.
| Mechanizm | Kierunek | Uwierzytelnianie | Odzyskiwanie po rozłączeniu |
|---|---|---|---|
| Webhooki | Bird wysyła na Twój serwer. | Twój odbiorca weryfikuje podpis za pomocą sekretu endpointu. | Nieudane dostarczenia są ponawiane. Pominięte zdarzenia można odtworzyć. |
| Realtime | Twój serwer publikuje do podłączonych klientów. | Klienci łączą się za pomocą klucza aplikacji. Prywatne subskrypcje wymagają autoryzacji backendu. | Ponownie łączący się klienci potrzebują odzyskiwania stanu. |
| Strumień SSE | Bird wysyła zmiany zasobów do sesji dashboardu. | Ciasteczko sesji dashboardu. | Odczytaj zasób ponownie, aby uzyskać jego stan. |
| Polling | Twoja aplikacja odpytuje Bird o stan. | Klucz API. | Późniejszy odczyt zwraca stan zasobu bez rekonstrukcji każdego przejścia. |
Kiedy webhooki są właściwą odpowiedzią?
Użyj webhooków, gdy Twój serwer musi reagować na zdarzenia i odzyskiwać pominięte dostarczenia.
Rejestrujesz publicznie dostępny endpoint HTTPS. Subskrybujesz go na potrzebne typy zdarzeń. Twój odbiorca najpierw weryfikuje podpis. Następnie zapisuje zdarzenie. Potwierdza dostarczenie, zanim rozpocznie się powolne przetwarzanie.
Bird wykonuje do ośmiu prób w ciągu około 27,5 godziny przed korektą odstępów. To okno daje odbiorcy czas na odzyskanie sprawności po awarii. Powtórne odtwarzanie pominiętych zdarzeń zapewnia dodatkową ścieżkę odzyskiwania.
Deduplikuj po webhook-id, ponieważ to samo zdarzenie może nadejść wielokrotnie. Porównuj czasy wystąpienia zdarzeń przed nadpisaniem stanu, ponieważ zdarzenia mogą nadchodzić w zmienionej kolejności.
Ponowne próby nieudanych webhooków opisuje limity odzyskiwania. Obsługa duplikatów opisuje bezpieczne zapisywanie zdarzenia przed zwróceniem sukcesu.
Kiedy zamiast tego użyć Realtime?
Użyj Realtime, gdy podłączona przeglądarka lub aplikacja potrzebuje aktualizacji w miarę ich publikowania przez Twój serwer.
Kanał to nazwane miejsce docelowe, które klienci subskrybują. Twój serwer publikuje zdarzenie pod tą nazwą, a zasubskrybowani klienci odbierają je przez swoje połączenia. Może to aktualizować stronę zamówienia, rozmowę na czacie lub wyświetlanie postępu bez przeładowania strony.
Realtime nie odtwarza wszystkich zdarzeń pominiętych przez rozłączonego klienta. Przechowuj trwały stan w bazie danych i odtwarzaj widok po ponownym połączeniu.
Kanał cache zachowuje ostatnie zdarzenie dla nowych subskrybentów, dopóki ta wartość jest dostępna. Nie przechowuje historii zdarzeń. Jeśli dwie aktualizacje nastąpią, gdy klient jest offline, ostatnia wartość w cache nie pozwoli odzyskać pośredniej aktualizacji.
Klucz aplikacji jest widoczny w kodzie klienta, więc publiczny kanał może odczytać każdy odwiedzający posiadający ten klucz. Kanał zaczynający się od private- wymaga autoryzacji subskrypcji przez Twój backend. Kanał presence- udostępnia również tożsamości zasubskrybowanych członków.
Nazwy kanałów przyjmują od 1 do 164 znaków, w tym litery, cyfry i _ - = @ , . ;. Prefiks wlicza się w ten limit, więc uwzględnij go przy walidacji generowanej nazwy.
Realtime wysyła też webhooki, gdy kanał zyskuje pierwszego subskrybenta lub traci ostatniego. Webhooki członkostwa informują, którzy członkowie dołączyli lub odeszli. Konfiguruj je w dashboardzie. Publish/subscribe a webhooki wyjaśnia, jak te dwa mechanizmy współdziałają.
Czy Bird ma endpoint SSE?
Bird ma endpoint SSE, getEventsStream, dla uwierzytelnionych sesji dashboardu.
GET /v1/events/stream raportuje zmiany zasobów API. Powiadomienie identyfikuje typ zasobu, identyfikator i czas wystąpienia, aby dashboard mógł pobrać dane zasobu.
Endpoint przyjmuje ciasteczko sesji dashboardu. Nie akceptuje klucza API, więc do integracji opartej na kluczu API użyj webhooków lub pollingu.
Kiedy polling jest właściwy?
Użyj pollingu, gdy potrzebujesz stanu zasobu, nie możesz odbierać przychodzących żądań lub nie masz publicznego zdarzenia dla danej zmiany.
Odpytuj, aby sprawdzić, czy operator zatwierdził Twój numer toll-free do wysyłania wiadomości tekstowych. Bird nie ma publicznego zdarzenia webhookowego dla tej decyzji weryfikacyjnej. Odczytuj weryfikację według harmonogramu przez bird sms tfn verifications get lub odpowiednie narzędzie agenta. Operacja polecenia jest poza publicznym pakietem API.
Polling sprawdza się też w sieci, która zezwala na żądania wychodzące, ale nie może udostępnić odbiorcy. Jeśli potrzebujesz tylko bieżącego stanu, odczyt zasobu pozwala uniknąć odbudowywania go z przeszłych zdarzeń.
Odczyty i listy zużywają budżety ograniczania liczby żądań na działające poświadczenie w ramach organizacji. Poczekaj przed ponownym żądaniem po odpowiedzi HTTP 429. Dostosuj interwał do tego, jak szybko Twoja aplikacja musi wykryć zmianę.
Webhooki, Realtime i limity żądań opisują konfigurację tych ścieżek.
Co wybrać?
Wybierz na podstawie tego, kto konsumuje aktualizację i co musi przetrwać rozłączenie.
- Webhooki, gdy Twój serwer musi przetwarzać zdarzenia z ponownymi próbami i odzyskiwaniem pominiętych zdarzeń.
- Realtime, gdy podłączone ekrany potrzebują aktualizacji i mogą odzyskać stan z zapisanych danych po ponownym połączeniu.
- Polling, gdy potrzebujesz stanu zasobu, nie możesz udostępnić odbiorcy lub nie masz publicznego zdarzenia.
- Strumień SSE do uwierzytelnionej sesji dashboardu Bird.
W skrócie
Wybierz webhooki do obsługi zdarzeń po stronie serwera.
Wykorzystaj ponowne próby i powtórne odtwarzanie pominiętych zdarzeń, gdy serwer musi odzyskać dostarczanie po awarii.
Wybierz Realtime do podłączonych ekranów.
Odtwórz widok z zapisanego stanu, gdy klient ponownie się połączy.
Wybierz polling do stanu zasobu.
Używaj pollingu, gdy nie możesz udostępnić odbiorcy, nie masz publicznego zdarzenia lub potrzebujesz tylko stanu zasobu.
Użyj SSE do sesji dashboardu Bird.
Strumień wymaga uwierzytelnienia sesji dashboardu.