Een bestelpagina kan tegelijkertijd een update nodig hebben als je database. Een webhook kan de databasewijziging triggeren. Je server kan vervolgens de resulterende state publiceren naar verbonden schermen.
Bird Realtime levert updates via WebSockets.
Wat zijn kanalen, leden en verbindingen?
Een kanaal groepeert abonnementen. Een verbinding is één open WebSocket. Een lid is een geauthenticeerde identiteit die wordt gedeeld met andere abonnees.
Een presence-kanaal deelt welke leden zijn geabonneerd. Eén lid kan meerdere verbindingen gebruiken, zoals aparte browsertabs.
Bird maakt een kanaal aan wanneer de eerste verbinding zich abonneert en verwijdert het nadat de laatste vertrekt. Je publiceert naar de kanaalnaam zonder een aparte kanaalresource aan te maken.
Elke verbinding krijgt een identifier. Je backend gebruikt die om een privéabonnement goed te keuren. Een publicatie kan die verbinding uitsluiten om te voorkomen dat de eigen update wordt teruggestuurd.
Als één lid drie tabs opent, kunnen die tabs drie verbindingen aanmaken onder één lididentiteit. Presence meldt dat het lid toetreedt bij de eerste verbinding en vertrekt nadat de laatste verbinding sluit. Het sluiten van de middelste tab verwijdert dat lid dus niet uit de lijst.
Wie mag zich abonneren?
Het prefix van het kanaal bepaalt of een abonnement autorisatie van je backend nodig heeft.
Je kiest een Bird-kanaalnaam van 1 tot 164 tekens, met letters, cijfers en _ - = @ , . ;. Neem het prefix mee in die lengte, zodat een gegenereerde privénaam binnen de limiet blijft.
| Naamprefix | Toegang |
|---|---|
| Geen private- of presence-prefix | Openbaar voor clients met de app-key. |
private- | Je backend keurt elk abonnement goed en ondertekent het. |
presence- | Je backend keurt het abonnement goed en levert de lididentiteit die wordt gedeeld met abonnees. |
private-encrypted- | Privétoegang met eventinhoud versleuteld met een sleutel die je beheert. |
De app-key is zichtbaar in clientcode, dus een onduidelijke publieke kanaalnaam beschermt geen vertrouwelijke gegevens. Bewaar het app-secret op je server en gebruik het om abonnementsgoedkeuringen te ondertekenen.
Bij een privéabonnement stuurt de client zijn verbindingsidentifier en kanaalnaam naar je autorisatie-endpoint. Je server controleert de toegang voordat de handtekening wordt teruggestuurd. Dat endpoint autoriseert toegang. Het ontvangt niet elk gepubliceerd event zoals een webhook dat zou doen.
Wat betekent het verschil in de praktijk?
Gebruik webhooks voor herstelbaar werk op je server. Gebruik pub/sub voor updates naar verbonden clients.
Een Bird-webhook stuurt een event naar een HTTPS-endpoint dat je beheert. Herhaalpogingen beslaan ongeveer 27,5 uur, met wachttijden die worden aangepast op basis van willekeurige variatie, overbelasting van de ontvanger en gevraagde vertragingen. Dat venster geeft je ontvanger tijd om te herstellen. Replay van gemiste events kan afleveringen herstellen die niet zijn gelukt.
Een Realtime-kanaal stuurt je gepubliceerde event naar geabonneerde clients. Een niet-verbonden client kan het missen. Een cache-kanaal kan het laatste event leveren aan een nieuwe abonnee zolang dat event in de cache staat. Het bewaart niet de tussenliggende eventgeschiedenis.
Houd vertrouwelijke serververwerking achter je webhookontvanger. Publiceer alleen de state die de geautoriseerde clients van het kanaal mogen zien.
Webhook-eventtypen komen uit de catalogus van Bird, zoals email.delivered. Met Realtime kies je zelf de eventnaam van je applicatie bij het publiceren. De naam event accepteert 1 tot 200 tekens. De prefixen bird: en bird_internal: zijn gereserveerd en kunnen niet worden gebruikt voor je applicatie-events.
Clients ontvangen ook protocolevents over abonnementssucces, lidwijzigingen en verbindingsaantallen. Die events beschrijven de verbinding of het kanaal zelf, niet de bestelling of het bericht van je applicatie.
Hoe gebruik ik ze samen?
Gebruik het opgeslagen event van de webhook om een Realtime-update voor verbonden clients aan te sturen.
Ontvang het bedrijfsevent op je server. Werk de duurzame state bij voordat je publiceert. Publiceer vervolgens de state die verbonden clients nodig hebben.
Bij een bestelpagina kan de webhook een database-update triggeren. Je server publiceert vervolgens de bijgewerkte bestelstatus, zodat de pagina van de klant verandert zonder te vernieuwen.
Houd die databasestate leesbaar na opnieuw verbinden, want een niet-verbonden client kan publicaties missen. Webhooks, polling of streaming vergelijkt de herstelopties.
Realtime heeft ook eigen webhooks voor kanaalbezetting en het toe- of uittreden van leden. Configureer deze via het dashboard in plaats van via de openbare webhooks-API.
Realtime-overzicht behandelt clientverbindingen. Webhooks behandelt requests die aan je server worden afgeleverd.
Kort gezegd
Een kanaal kan veel abonnees hebben.
Een webhook-request gaat naar één geregistreerd endpoint. Een publicatie gaat naar clients die zijn geabonneerd op het kanaal.
Privéabonnementen vereisen goedkeuring van de backend.
De app-key is zichtbaar in clientcode. Private- en presence-prefixen vereisen een handtekening van je server.
Leden kunnen meerdere verbindingen hebben.
Een lid dat drie tabs gebruikt, treedt toe tot presence bij de eerste verbinding en vertrekt nadat de laatste verbinding sluit.
Combineer afleverherstel met een verbonden weergave.
Gebruik webhookherstel voor serverevents en opgeslagen state om een Realtime-weergave na een verbroken verbinding te herstellen.