Senden Sie Live-Nachrichten und Anwesenheit mit dem JavaScript SDK
Die alltäglichen Abläufe von aura.realtime, wobei das Verhalten jedes Aufrufs anhand eines laufenden Stapels beobachtet wird.
Kanäle und ihr Status#
Ein Kanal ist ein benannter Raum. Clients, die denselben Namen öffnen, erhalten gegenseitig die Nachrichten. Wenn Sie ein Abonnement abschließen, stellt der Client selbständig eine Verbindung her.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// 'ABONNENT' | 'CHANNEL_ERROR' | 'TIMED_OUT' | 'GESCHLOSSEN'
if (status === 'SUBSCRIBED') console.log('ready')
})
Nur nach SUBSCRIBED senden. Davor oder nach einer Ablehnung gibt send() einen Status wie not_connected oder requires_subscription zurück, anstatt zu senden. Kanäle sind auf Ihr Projekt beschränkt: Zwei Projekte können denselben Namen verwenden, ohne sich gegenseitig zu sehen.
Broadcast-Nachrichten#
// Empfangen
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // { event: 'ping', n: 1, text: 'hello' }
})
// Senden, sobald Sie sich angemeldet haben
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'ok'
In einem echten Durchlauf empfing ein zweiter angemeldeter Client die Nachricht in weniger als zwei Sekunden.
Der Nachricht, die Sie erhalten, wird der Ereignisname zu payload hinzugefügt: { "event": "ping", "n": 1, … }. Eine Nutzlast, die über einen eigenen event-Schlüssel verfügt, wird abgelehnt (channel.send gibt 'invalid_payload' zurück, httpBroadcast gibt realtime_payload_event_reserved zurück): Benennen Sie den Schlüssel um, zum Beispiel kind.
- Sie erhalten standardmäßig keine eigenen Nachrichten. Öffnen Sie den Kanal mit
{ config: { broadcast: { self: true } } }, um sie zu empfangen. - Eine Nachricht trägt
id,topic,timestamp,eventundpayload.
Präsenz#
„Präsenz“ zeigt an, wer mit einem Kanal verbunden ist, mit einem von Ihnen gewählten Status.
const lobby = aura.realtime.channel('lobby', { config: { presence: { key: user.id } } })
lobby.on('presence', { event: 'sync' }, () => {
console.log(lobby.presenceState())
})
lobby.subscribe(async (status) => {
if (status === 'SUBSCRIBED') await lobby.track({ name: 'Bob' })
})
presenceState() wird durch die Benutzer-ID verschlüsselt. Jeder Eintrag listet die Verbindungen des Benutzers auf:
{
"d6ba3994-…": [
{ "client_id": "936cb015-…", "user_id": "d6ba3994-…", "metadata": { "name": "Bob" },
"joined_at": "2026-10-12T19:32:19.093Z", "last_seen": "2026-10-12T19:32:19.096Z" }
]
}
untrack() entfernt Sie aus der Liste und das Verlassen des Kanals oder das Schließen der Seite erledigt dies für Sie.
Datenbankänderungen#
postgres_changes arbeitet an Projekten mit einer eigenen Datenbank. Aktivieren Sie zuerst jede Tabelle: PUT /v1/db/schema/tables/{table}/realtime (oder aura db table realtime <table> on) mit dem Hauptteil {"enabled": true} und einem service_role-Schlüssel. Das Zuhören beginnt, wenn sich der erste Kunde anmeldet, und endet einige Minuten, nachdem der letzte Kunde das Abonnement verlässt. Die Lieferung erfolgt mindestens einmal: Nach einem Serverneustart kann eine Änderung zweimal eintreffen. Machen Sie Ihren Handler daher idempotent, indem Sie beispielsweise den Primärschlüssel der Zeile eingeben. Ein ausgelasteter Cluster kann aufgrund eines Kapazitätsfehlers einen neuen Listener ablehnen; Versuchen Sie es in Kürze noch einmal. Jeder Kanalname funktioniert: table jedes Filters wählt die Tabelle aus, die überwacht werden soll, und ein Kanal kann mehrere Tabellen überwachen. Auf einem Kanal, der nicht den Namen db:<schema>.<table> hat, benötigt jeder Filter einen table. Der erste Abonnent kann bis zu 5 Sekunden lang Änderungen erhalten, die unmittelbar vor dem Abonnieren vorgenommen wurden. Änderungen werden eine Stunde lang zur Wiederherstellung aufbewahrt und dann gelöscht. Wenn der Cluster voll ist, schlägt das Abonnement mit capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez fehl. Wenn die Wiedergabe länger als eine Minute unterbrochen bleibt, wechselt der Kanal zu CHANNEL_ERROR und dann zurück zu SUBSCRIBED, sobald die Wiedergabe wiederhergestellt ist. Sie müssen sich nicht erneut anmelden. Wenn ein Ausfall die einstündige Aufbewahrung überschreitet, empfängt der Kanal auch CHANNEL_ERROR mit changements postgres_changes perdus pendant l'interruption, resynchronisez: Laden Sie die Daten aus der Datenbank neu. Eine Änderung behält bei jeder Übermittlung den gleichen id bei, Sie können also auch einen id überspringen, den Sie bereits bearbeitet haben. Die Zeile einer Löschung ist nicht mehr vorhanden, daher kann die Sicherheit auf Zeilenebene nicht ausgewertet werden. In einer Tabelle mit Sicherheit auf Zeilenebene wird ein DELETE daher nur an Abonnenten übermittelt, deren Rolle eine SELECT-Richtlinie für die Tabelle hat (oder RLS umgeht, wie service_role): Ein Besucher (anon) ohne Leserichtlinie erhält sie nicht. Bei einer Tabelle ohne Sicherheit auf Zeilenebene erhält sie jeder Abonnent. payload.old eines DELETE enthält nur die Primärschlüsselspalten (nichts, wenn die Tabelle keinen Primärschlüssel hat), und ein Filter für eine andere Spalte stimmt nie mit einem Löschvorgang überein. Bei einem UPDATE enthält payload.old außerdem nur die Primärschlüsselspalten der vorherigen Zeile (ihre vorherigen Werte, wenn sich der Schlüssel geändert hat), niemals die anderen Werte: Die Sicherheit auf Zeilenebene wird nur für die neue Zeile überprüft. Der Filter eines UPDATE gilt für die neue Zeile. Halten Sie vertrauliche Informationen von Primärschlüsseln fern.
const changes = aura.realtime
.channel('todos')
.on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (payload) => {
console.log(payload.eventType, payload.new)
})
.subscribe((status) => {
if (status === 'CHANNEL_ERROR') console.warn('database changes are not available for this project')
})
Aufräumen#
room.unsubscribe() // einen Kanal verlassen
aura.realtime.removeChannel(room) // geh und vergiss es
aura.realtime.removeAllChannels() // Verlasse jeden Kanal
aura.realtime.disconnect() // Schließen Sie die Verbindung
Beobachten Sie die Verbindung mit aura.realtime.onStateChange(callback) und onError(callback). Nach einem Verbindungsabbruch stellt der Client die Verbindung selbst wieder her, es sei denn, Sie rufen setAutoReconnect(false) auf.