Realtime-Übersicht

Realtime sendet Ereignisse über WebSockets an verbundene Clients. Ihr Server veröffentlicht ein Ereignis auf einem benannten Channel, und abonnierte Clients empfangen es ohne Polling.

Verwenden Sie Realtime für Änderungen, die ein Client sofort benötigt, ohne eine weitere Anfrage zu stellen, etwa Bestellstatus-Updates, Chat-Nachrichten, Dashboard-Änderungen oder abgeschlossene Hintergrund-Jobs.

Channels, Members und Connections

Drei Begriffe beschreiben das Modell. Sie sind nicht austauschbar.

Ein Channel ist ein benannter Raum. Er existiert, solange mindestens eine Connection abonniert ist, und verschwindet, wenn die letzte ihn verlässt. Channel-Namen erlauben bis zu 164 Buchstaben, Ziffern und folgende Zeichen: _ - = @ , . ;.

Eine Connection ist ein offener WebSocket. Sie erhält beim Verbinden eine ID (26896.319537). Die Autorisierung signiert diese ID, und beim Publizieren kann sie von der Zustellung ausgeschlossen werden.

Ein Member ist eine authentifizierte Identität auf einem Presence-Channel. Ein Member kann mehrere Connections halten, zum Beispiel drei Browser-Tabs. Presence-Ereignisse werden ausgelöst, wenn die erste Connection des Members beitritt und die letzte den Channel verlässt. Zwischenzeitliche Tabs erzeugen keine Ereignisse.

Die drei Channel-Typen

Das Präfix des Channel-Namens bestimmt den Channel-Typ und sein Autorisierungsverhalten.

Name	Wer abonnieren kann	Hat Members
orders	jeder mit dem App-Key	nein
private-orders	nur Clients, die Ihr Backend signiert	nein
presence-lobby	nur Clients, die Ihr Backend signiert	ja

Ein Public-Channel ist für jeden mit dem App-Key lesbar, der im Client-Code mitgeliefert wird. Veröffentlichen Sie nur Daten, die jeder Besucher sehen darf. Siehe Public-Channels.

Ein Private-Channel verlangt von Ihrem Backend, jedes Abonnement zu genehmigen. Der Client sendet die Connection-ID und den Channel-Namen an Ihren Endpunkt, der eine mit dem App-Secret berechnete Signatur zurückgibt. Siehe Private-Channels. Ein private-encrypted-…-Channel verschlüsselt zusätzlich die Payloads mit einem Schlüssel auf Ihren Servern. Siehe Verschlüsselte Channels.

Ein Presence-Channel ergänzt die Private-Channel-Autorisierung um eine Identität. Jeder Abonnent empfängt die Member-Liste und Änderungen über member_id und optionale member_info. Siehe Presence-Channels.

Ereignisse, die der Client empfängt

Application-Ereignisse gehören Ihnen: Sie wählen den Namen beim Publizieren (order-updated, message.created) und binden einen Handler daran. Daneben gibt der Client Lifecycle-Ereignisse unter dem Präfix bird: weiter, die Sie genauso binden wie Ihre eigenen:

bird:subscription_succeeded wird einmal pro Channel ausgelöst, wenn das Abonnement aktiv ist. Auf einem Presence-Channel enthält es die aktuelle Member-Liste, sodass Sie den Raum rendern können, bevor sich jemand bewegt.
bird:member_added und bird:member_removed werden auf Presence-Channels ausgelöst, wenn Members beitreten oder gehen. member_added wird ausgelöst, wenn die erste Connection einer Person abonniert; member_removed erst, wenn deren letzte Connection geht. Ein zweiter Tab, der geöffnet und geschlossen wird, erzeugt keines von beiden.
bird:connection_count meldet, wie viele Connections den Channel abonniert haben, wenn die App Connection-Zählung und Connection-Count-Ereignisse aktiviert hat. Es zählt Connections, daher zählt der Member mit drei Tabs als drei.
bird:subscription_error wird ausgelöst, wenn ein Abonnement abgelehnt wird, meist weil die Autorisierung fehlgeschlagen ist.

Namen, die mit client- beginnen, sind für Ereignisse reserviert, die Clients direkt untereinander senden. Das ist eine separate App-Einstellung und nur auf Private- und Presence-Channels erlaubt.

Ihr Server kann Ereignisse auch als Webhooks empfangen, wenn ein Channel belegt oder frei wird und wenn Members beitreten oder gehen. Diese kommen als realtime.*-Ereignisse über dieselben Webhook-Endpunkte wie der Rest von Bird an.

Die Clients

Drei Clients empfangen Ereignisse über dasselbe Protokoll. Verwenden Sie @messagebird/realtime für Browser und Node.js, BirdRealtime für iOS, macOS und Linux oder com.messagebird:bird-realtime für Android und die Server-JVM. Jeder unterstützt Subscriptions, Bindings, Presence, signin() und Client-Ereignisse.

Bewahren Sie das App-Secret auf Ihrem Server auf. Server-SDKs verwenden es, um Ereignisse zu publizieren, Channels zu autorisieren und Members zu trennen.

Apps, Keys und Regionen

Eine App ist eine isolierte Umgebung mit eigenen Zugangsdaten und einem eigenen Channel-Namespace. Zwei Apps sehen niemals die Channels der jeweils anderen, was eine App zur richtigen Grenze zwischen Ihrer Staging- und Produktionsumgebung macht.

Jede App verwendet eine unveränderliche Region, die bei der Erstellung gewählt wird. Verwenden Sie Realtime-Regionen auflisten, um die akzeptierten Bezeichner abzurufen, und wählen Sie die Region, die Ihren Nutzern am nächsten liegt.

Jede App hat drei Werte mit unterschiedlichen Verwendungszwecken:

Die App-ID (rap_…) identifiziert die App in Bird API-Aufrufen und erscheint in jedem /v1/realtime/apps/…-Pfad.
Der Key ist öffentlich. Browser verbinden sich damit, und er kann bedenkenlos im Client-Code mitgeliefert werden.
Das Secret wird zusammen mit dem Key verwendet, um serverseitige Aufrufe zu authentifizieren und die Channel-Autorisierung zu signieren. Es wird einmalig bei der Erstellung angezeigt. Jeder, der es besitzt, kann in Ihrer App publizieren und Presence-Identitäten fälschen.

Verwalten Sie Apps und rotieren Sie Keys auf der Seite Realtime-Apps. Erstellen Sie einen zweiten Key, deployen Sie ihn und widerrufen Sie dann den alten Key.

Sichtbarkeit

Die Seite Realtime-Metriken zeigt drei Werte pro App oder über den gesamten Workspace für das gewählte Zeitfenster:

Max. Connections ist die höchste Anzahl gleichzeitig offener Connections innerhalb des Zeitfensters. Dieser Spitzenwert ist der Wert, auf den das Connection-Limit angewendet wird.
Durchschnittliche Connections ist der Mittelwert der täglichen Spitzenwerte. Es wird nicht jeder Messwert gemittelt. Ein Workspace, der jeden Nachmittag Spitzen erreicht und nachts ruht, zeigt einen Durchschnitt deutlich über seinen ruhigen Stunden.
Messages zählt Ereigniszustellungen, eine pro Channel: Ein Publish an 50 Channels zählt als 50. Eingeschlossen sind auch Ereignisse, die das Protokoll in Ihrem Namen sendet, also Presence-Beitritte und Connection-Count-Updates. Deshalb kann die Zahl über den Publishes liegen, die Ihr Code ausgelöst hat.

Die Nutzung wird in Einminuten-Intervallen aggregiert, daher kann es einige Minuten dauern, bis aktueller Traffic erscheint. Die Nutzungs-API ist derzeit nur im Dashboard verfügbar. Für programmatische Sichtbarkeit erfassen Sie Publishes in Ihren Systemen oder leiten Aktivität aus realtime.*-Webhooks ab.

Pläne und Limits

Der kostenlose Plan umfasst 100 gleichzeitige Connections und 200.000 Messages pro Tag, über alle Apps eines Workspace hinweg. Weitere Apps anzulegen erhöht das Limit nicht, da es für den gesamten Workspace gilt.

Bezahlte Pläne beginnen bei 25 $ pro Monat für 250 gleichzeitige Connections und 500.000 Messages pro Tag und skalieren bis zu 30.000 Connections und 90 Millionen Messages pro Tag. Realtime-Preise listet jede Stufe auf.

Pro-Anfrage-Limits gelten in jedem Plan: Ein Publish benennt maximal 100 Channels, ein Batch enthält maximal 10 Ereignisse, und ein Event-Payload ist auf 10 KB serialisiert begrenzt.

Nächste Schritte

Senden Sie Ihr erstes Realtime-Ereignis führt Sie durch den gesamten Ablauf von Anfang bis Ende.
Ereignisse publizieren behandelt das Publizieren von Ihrem Server, Batching und das Ausschließen des auslösenden Clients.
Channels autorisieren ist der Vertrag, den Ihr Backend für Private- und Presence-Channels implementiert.

Verwandte Ressourcen