Overzicht van Realtime
Realtime pusht events naar verbonden clients via WebSockets. Je server publiceert een event naar een named channel, en geabonneerde clients ontvangen het zonder polling.
Gebruik Realtime voor wijzigingen die een client nodig heeft zonder een nieuw verzoek te doen, zoals orderupdates, chatberichten, dashboardwijzigingen of afgeronde achtergrondtaken.
Channels, members en connections
Drie woorden beschrijven het model. Ze zijn niet uitwisselbaar.
Een channel is een named room. Het bestaat zolang minstens één connection is geabonneerd en verdwijnt wanneer de laatste vertrekt. Channelnamen staan maximaal 164 letters, cijfers en deze tekens toe: _ - = @ , . ;.
Een connection is één open WebSocket. Het ontvangt een ID (26896.319537) bij het verbinden. Autorisatie ondertekent dit ID, en bij het publiceren kun je het uitsluiten van levering.
Een member is een geauthenticeerde identiteit op een presence channel. Eén member kan meerdere connections hebben, zoals drie browsertabbladen. Presence-events worden afgevuurd wanneer de eerste connection van de member zich aanmeldt en de laatste vertrekt. Tussenliggende tabbladen produceren ze niet.
De drie channeltypen
Het prefix van de channelnaam bepaalt het channeltype en het autorisatiegedrag.
| Naam | Wie kan abonneren | Heeft members |
|---|---|---|
| orders | iedereen met de app key | nee |
| private-orders | alleen clients die je backend ondertekent | nee |
| presence-lobby | alleen clients die je backend ondertekent | ja |
Een public channel is leesbaar voor iedereen met de app key, die in clientcode wordt meegeleverd. Publiceer alleen data die elke bezoeker mag zien. Zie Public channels.
Een private channel vraagt je backend om elk abonnement goed te keuren. De client post het connection-ID en de channelnaam naar je endpoint, dat een handtekening teruggeeft die is berekend met het app secret. Zie Private channels. Een private-encrypted-…-channel versleutelt ook payloads met een sleutel die je servers beheren. Zie Encrypted channels.
Een presence channel voegt een identiteit toe aan private-channel-autorisatie. Elke abonnee ontvangt de memberlijst en wijzigingen via member_id en optioneel member_info. Zie Presence channels.
Events die de client ontvangt
Application events zijn van jou: je kiest de naam bij het publiceren (order-updated, message.created) en bindt er een handler aan. Daarnaast zendt de client lifecycle-events opnieuw uit onder het bird:-prefix, die je op dezelfde manier bindt als je eigen events:
- bird:subscription_succeeded wordt eenmaal per channel afgevuurd wanneer het abonnement actief is. Op een presence channel bevat het de huidige memberlijst, zodat je de room kunt renderen voordat iemand beweegt.
- bird:member_added en bird:member_removed worden afgevuurd op presence channels wanneer members aankomen en vertrekken. member_added wordt afgevuurd wanneer de eerste connection van een persoon zich abonneert; member_removed pas wanneer de laatste vertrekt. Een tweede tabblad dat opent en sluit produceert geen van beide.
- bird:connection_count rapporteert hoeveel connections geabonneerd zijn op het channel, als de app connection counting en connection count events heeft ingeschakeld. Het telt connections, dus de member met drie tabbladen telt als drie.
- bird:subscription_error wordt afgevuurd wanneer een abonnement wordt geweigerd, meestal omdat autorisatie is mislukt.
Namen die beginnen met client- zijn gereserveerd voor events die clients rechtstreeks naar elkaar sturen. Dit is een aparte app-instelling en alleen toegestaan op private en presence channels.
Je server kan ook events ontvangen, als webhooks, wanneer een channel bezet of leeg wordt en wanneer members toetreden of vertrekken. Die komen binnen als realtime.*-events via dezelfde webhook-endpoints als de rest van Bird.
De clients
Drie clients ontvangen events via hetzelfde protocol. Gebruik @messagebird/realtime voor browsers en Node.js, BirdRealtime voor iOS, macOS en Linux, of com.messagebird:bird-realtime voor Android en de server-JVM. Elk ondersteunt subscriptions, bindings, presence, signin() en client events.
Bewaar het app secret op je server. Server-SDK's gebruiken het om events te publiceren, channels te autoriseren en members te disconnecten.
Apps, keys en regio's
Een app is een geïsoleerde omgeving met eigen credentials en een eigen channel-namespace. Twee apps zien nooit elkaars channels, en dat maakt een app de juiste grens tussen je staging- en productieomgevingen.
Elke app gebruikt een onveranderlijke regio die bij het aanmaken wordt gekozen. Gebruik Realtime-regio's ophalen om de geaccepteerde identifiers op te halen, en kies de regio die het dichtst bij je gebruikers ligt.
Elke app heeft drie waarden met verschillende toepassingen:
- Het app-ID (rap_…) identificeert de app in Bird API-aanroepen en verschijnt in elk /v1/realtime/apps/…-pad.
- De key is publiek. Browsers verbinden ermee, en het is veilig om deze in clientcode mee te leveren.
- Het secret hoort bij de key om server-side aanroepen te authenticeren en om channelautorisatie te ondertekenen. Het wordt eenmalig getoond bij het aanmaken. Iedereen die het bezit kan publiceren naar je app en presence-identiteiten vervalsen.
Beheer apps en roteer keys op de pagina Realtime apps. Maak een tweede key aan, deploy deze en trek daarna de oude key in.
Zichtbaarheid
De pagina Realtime-metrics rapporteert drie waarden per app of over de hele werkruimte voor het geselecteerde venster:
- Max connections is het hoogste aantal connections dat op hetzelfde moment open is binnen het venster. Deze piek is de waarde waarop de connectionlimiet van toepassing is.
- Average connections is het gemiddelde van de dagelijkse pieken. Het middelt niet elk sample. Een werkruimte die elke middag piekt en 's nachts stilligt, toont een gemiddelde dat ruim boven de rustige uren ligt.
- Messages telt eventleveringen, één per channel: een publish die 50 channels noemt telt als 50. Het omvat ook de events die het protocol namens jou verstuurt, dus presence-joins en connection-count-updates vallen in hetzelfde getal. Daardoor kan het vooruitlopen op de publishes die jouw code heeft gedaan.
Gebruik wordt geaggregeerd in buckets van één minuut, dus recent verkeer kan enkele minuten nodig hebben om te verschijnen. De usage-API is momenteel alleen beschikbaar voor het dashboard. Leg voor programmatische zichtbaarheid publishes vast in je eigen systemen of leid activiteit af uit realtime.*-webhooks.
Abonnementen en limieten
Het gratis abonnement dekt 100 gelijktijdige connections en 200.000 berichten per dag, over alle apps van een werkruimte. Meer apps aanmaken verhoogt het plafond niet, omdat het op de werkruimte van toepassing is.
Betaalde abonnementen beginnen bij $ 25 per maand voor 250 gelijktijdige connections en 500.000 berichten per dag, en schalen op tot 30.000 connections en 90 miljoen berichten per dag. Realtime-prijzen toont elke stap.
Limieten per verzoek gelden voor elk abonnement: één publish noemt maximaal 100 channels, een batch bevat maximaal 10 events en een event-payload is beperkt tot 10 KB geserialiseerd.
Volgende stappen
- Verstuur je eerste realtime event doorloopt de hele cyclus van begin tot eind.
- Events publiceren behandelt het publiceren vanaf je server, batching en het uitsluiten van de oorspronkelijke client.
- Channels autoriseren is het contract dat je backend implementeert voor private en presence channels.
Gerelateerde bronnen
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.