Realtime-Kanäle
Ein Kanal ist ein Name. Kein Provisionieren nötig.
Ein Kanal existiert, sobald sich etwas darauf abonniert, und verschwindet, wenn die letzte Verbindung ihn verlässt. Sein Name bestimmt den Typ: Public für alles, was ein Besucher lesen darf, Private für alles, was einem Kunden zugeordnet ist, Presence für einen Raum mit Teilnehmerliste, und ein Cache-Präfix für State, den ein spät hinzukommender Teilnehmer sofort benötigt.
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());
Täglich vertraut von Teams, die erstklassige Software entwickeln
Weitere Kundenberichte lesenDas Präfix ist die Konfiguration.
Es gibt kein Kanalregister, das Sie synchron halten müssen.
Kanäle sind das Adressierungsmodell der Bird Realtime API. Sie erstellen nie einen: Sie abonnieren einen Namen, und die ersten drei Zeichen dieses Namens teilen dem Edge mit, wie er ihn behandeln soll. Ein Name ohne Präfix ist öffentlich. private- fordert Ihr Backend auf, jedes Abonnement zu genehmigen. presence- tut dasselbe und verknüpft eine Identität. private-encrypted- versiegelt die Nutzlast mit einem Schlüssel, den Bird niemals besitzt. Namen umfassen bis zu 164 Zeichen, unterscheiden Groß- und Kleinschreibung und sind der eine Teil eines Kanals, über den Sie sorgfältig nachdenken sollten, denn ein öffentlicher Name ist für jeden sichtbar, der den App-Schlüssel besitzt.
Fünf Arten von Räumen.
Gleiches Protokoll, gleicher Client, gleicher Publish-Aufruf. Der Name macht den Unterschied.
- 01
Public-Kanäle.
Kein Autorisierungsendpunkt, keine Registrierung. Jeder mit dem App-Schlüssel kann abonnieren – richtig für Build-Ergebnisse, Live-Ergebnisse, Fluginformationen oder eine Statusseite, falsch für alles, was einem einzelnen Kunden zugeordnet ist. Halten Sie Bezeichner aus dem Namen heraus: orders verrät nichts, orders-user-4821 verrät, dass Benutzer 4821 existiert.
- 02
Private-Kanäle.
Ein Name mit private- leitet das Abonnement über Ihren eigenen Endpunkt, der die Sitzung prüft und die Verbindungs-ID sowie den Kanalnamen mit dem App-Secret signiert. Ihre Regeln, Ihre Sitzung, Ihr 403. Der Edge verifiziert die Signatur und nichts anderes erreicht den Kanal.
- 03
Presence-Kanäle.
Private-Kanal-Autorisierung plus eine Identität, sodass jeder Abonnent die Teilnehmerliste erhält und über An- und Abmeldungen informiert wird. Dies ist der einzige Kanaltyp mit einer Teilnehmerliste.
- 04
Encrypted-Kanäle.
Ein private-encrypted-Kanal überträgt Nutzlasten, die Ihr Server mit einem 32-Byte-Hauptschlüssel versiegelt, der nie in einer Realtime-Anfrage erscheint. Der Edge und alles zwischen ihm und dem Browser sehen Chiffretext. Kanal- und Eventnamen bleiben im Klartext – wählen Sie also Namen, die nicht verraten, was Sie schützen.
- 05
Cache-Kanäle.
Stellen Sie dem Namen cache- voran, nach einem eventuellen Typpräfix, und der Kanal merkt sich sein letztes per API veröffentlichtes Event und spielt es jedem neuen Abonnenten erneut vor. Das Abonnement dient gleichzeitig als initialer State-Abruf. Zwei Einschränkungen, die Sie beim Design berücksichtigen sollten: Nur das neueste Event wird gespeichert, und es kann vor dem 30-Minuten-Limit ablaufen. Packen Sie daher den gesamten State in jede Nutzlast und befüllen Sie ihn über den Cache-Miss-Webhook neu, statt davon auszugehen, dass der Cache gefüllt ist.
Ein Publish, bis zu hundert Kanäle.
Publizieren ist ein gewöhnlicher REST-Aufruf von Ihrem Server. Nennen Sie bis zu 100 Kanäle in einer Anfrage und der Edge verteilt das Event an alle. Ein Batch enthält bis zu 10 unabhängige Events, jedes an seinen eigenen Kanal. Übergeben Sie die Verbindungs-ID des handelnden Clients als exclude_connection_id und der Tab, der die Änderung bereits lokal angewendet hat, wird übersprungen. Fordern Sie Verbindungs- oder Teilnehmerzahlen mit include an und die Antwort liefert Ihnen den Zustand jedes Kanals zum Zeitpunkt des Publizierens. Wiederholen Sie die Anfrage mit demselben Idempotency-Key und Sie liefern nicht doppelt aus.
// 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 können direkt miteinander kommunizieren.
Ein Tipp-Indikator oder eine Cursorposition muss Ihre API nicht besuchen. Aktivieren Sie Client-Events in der App und ein abonnierter Client kann ein Event namens client-something direkt an die anderen im Kanal senden, begrenzt auf 10 pro Sekunde pro Verbindung. Sie funktionieren nur auf Private- und Presence-Kanälen, und das ist beabsichtigt: Der App-Schlüssel wird in Ihrer Seite ausgeliefert, also macht erst die Autorisierung einen Client vertrauenswürdig genug zum Senden. Behandeln Sie eingehende Daten als Signal, nie als autoritativen State, denn der Edge validiert die Nutzlast nicht.
Was ein Kanal speichert und was nicht.
Ein Publish kehrt zurück, sobald der Edge das Event angenommen hat. Die Zustellung erfolgt asynchron, es gibt keine Empfangsbestätigung pro Client, und ein Client, der während der Zustellung die Verbindung verliert, bekommt das Event bei Reconnect nicht erneut. Das ist der ehrliche Vertrag, und deshalb gehört dauerhafter State in Ihre Datenbank – Events kündigen nur an, dass er sich geändert hat. Limits sind auf jedem Plan gleich: 100 Kanäle pro Publish, 10 Events pro Batch, 10 KB pro Nutzlast, 164 Zeichen für Kanalnamen.
Mehr dazu in der Dokumentation.
Die Realtime-Übersicht definiert Kanäle, Mitglieder und Verbindungen auf einer Seite. Events veröffentlichen behandelt Broadcast, Batch und Ausschluss, Cache-Kanäle erklärt die Wiedergabe, und Kanalzustand abfragen ist der serverseitige Read für Belegung und Zähler.
In die Praxis umsetzen.
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Der Rest von Realtime
Eine App, ein Schlüsselpaar. Entdecken Sie die weiteren Funktionen.
Abonnieren Sie einen Namen und beginnen Sie mit dem Publizieren.
Erstellen Sie eine App, liefern Sie den öffentlichen Schlüssel in Ihrem Client aus und bewahren Sie das Secret auf Ihrem Server. Der kostenlose Plan umfasst 100 gleichzeitige Verbindungen.