Een kanaal bestaat zodra iets erop abonneert en verdwijnt wanneer de laatste verbinding vertrekt. De naam bepaalt het type: publiek voor alles wat een bezoeker mag lezen, privé voor alles wat aan een klant is gekoppeld, presence voor een ruimte met een deelnemerslijst, en een cache-prefix voor state die een late deelnemer direct nodig heeft.
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());
Het prefix is de configuratie.
Er is geen kanaalregister om bij te houden.
Kanalen zijn het adresseringsmodel van de Bird Realtime API. U maakt er nooit een aan: u abonneert op een naam, en de eerste drie tekens van die naam vertellen de edge hoe hij ermee moet omgaan. Een naam zonder prefix is publiek. private- vraagt uw backend om elk abonnement goed te keuren. presence- doet hetzelfde en koppelt er een identiteit aan. private-encrypted- verzegelt de payload met een sleutel die Bird nooit bezit. Namen zijn maximaal 164 tekens, hoofdlettergevoelig, en het enige onderdeel van een kanaal waar u goed over na moet denken, want een publieke naam is zichtbaar voor iedereen met de app-sleutel.
Vijf soorten ruimtes.
Hetzelfde protocol, dezelfde client, dezelfde publish-aanroep. De naam is wat verschilt.
- 01
Publieke kanalen.
Geen autorisatie-endpoint, geen registratie. Iedereen met de app-sleutel kan abonneren, waardoor ze geschikt zijn voor buildresultaten, live scores, vluchtinformatie of een statuspagina, en ongeschikt voor alles wat aan één klant is gekoppeld. Houd identificatiegegevens uit de naam: orders onthult niets, orders-user-4821 onthult dat gebruiker 4821 bestaat.
- 02
Privékanalen.
Een private-naam routeert het abonnement via uw eigen endpoint, dat de sessie controleert en de verbindings-ID en kanaalnaam ondertekent met het app-geheim. Uw regels, uw sessie, uw 403. De edge verifieert de handtekening en niets anders bereikt het kanaal.
- 03
Presence-kanalen.
Privékanaal-autorisatie plus een identiteit, zodat elke abonnee de ledenlijst krijgt en op de hoogte wordt gebracht van aankomsten en vertrekken. Dit is het enige kanaaltype met een deelnemerslijst.
- 04
Versleutelde kanalen.
Een private-encrypted-kanaal draagt payloads die uw server verzegelt met een 32-byte mastersleutel die nooit in een Realtime-verzoek verschijnt. De edge en alles ertussen en de browser zien cijfertekst. Kanaal- en eventnamen blijven leesbaar, dus kies namen die niet onthullen wat u beschermt.
- 05
Cache-kanalen.
Begin de naam met cache-, na een eventueel typeprefix, en het kanaal onthoudt het laatste via de API gepubliceerde event en speelt het af voor elke nieuwe abonnee. Het abonnement fungeert tegelijk als initiële state-ophaling. Twee beperkingen om rekening mee te houden: alleen het meest recente event wordt bewaard, en het kan verlopen vóór het 30-minutenplafond, dus stop de volledige state in elke payload en vul opnieuw aan via de cache-miss-webhook in plaats van aan te nemen dat de cache warm is.
Eén publish, tot honderd kanalen.
Publiceren is een gewone REST-aanroep vanaf uw server. Noem tot 100 kanalen in één verzoek en de edge verspreidt het event naar allemaal. Een batch bevat maximaal 10 ongerelateerde events, elk naar een eigen kanaal. Geef de verbindings-ID van de actieve client door als exclude_connection_id en het tabblad dat de wijziging al lokaal heeft toegepast wordt overgeslagen. Vraag verbindings- of ledenaantallen op met include en het antwoord vertelt u de staat van elk kanaal op het moment van publicatie. Probeer opnieuw met dezelfde idempotency-sleutel en u levert niet dubbel af.
// 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);
}
Clients kunnen rechtstreeks met elkaar communiceren.
Een typindicator of cursorpositie hoeft uw API niet te bezoeken. Schakel client-events in op de app en een geabonneerde client kan een event met de naam client-iets rechtstreeks naar de anderen in het kanaal sturen, begrensd op 10 per seconde per verbinding. Ze werken alleen op privé- en presence-kanalen, en dat is bewust: de app-sleutel staat in uw pagina, dus autorisatie is wat een client betrouwbaar genoeg maakt om te broadcasten. Behandel wat binnenkomt als een signaal, nooit als gezaghebbende state, want de edge valideert de payload niet.
Wat een kanaal wel en niet onthoudt.
Een publish retourneert zodra de edge het event heeft geaccepteerd. Aflevering is asynchroon, er is geen ontvangstbevestiging per client, en een client die halverwege de aflevering wegvalt krijgt het event niet opnieuw bij herverbinding. Dat is het eerlijke contract, en daarom hoort duurzame state in uw database thuis en kondigen events aan dat die is gewijzigd. Limieten zijn op elk plan hetzelfde: 100 kanalen per publish, 10 events per batch, 10 KB per payload, kanaalnamen van 164 tekens.
Ga dieper in de documentatie.
Het Realtime-overzicht definieert kanalen, leden en verbindingen op één pagina. Events publiceren behandelt broadcast, batch en uitsluiting, cache-kanalen legt de replay uit, en kanaalstatus opvragen is de serverside-leesbewerking voor bezetting en aantallen.
Breng het in de praktijk.
Ga verder met de documentatie, gidsen en voorbeelden voor dit onderwerp. De bronnen zijn in het Engels.
De rest van Realtime
Eén app, één sleutelpaar. Ontdek de andere mogelijkheden.
Abonneer je op een naam en begin met publiceren.
Maak een app, gebruik de publieke sleutel in je client en bewaar het geheim op je server. Het gratis abonnement dekt 100 gelijktijdige verbindingen.