Stuur live berichten en aanwezigheid met de JavaScript SDK
De dagelijkse stromen van aura.realtime, waarbij het gedrag van elke oproep wordt waargenomen tegen een lopende stapel.
Kanalen en hun status#
Een kanaal is een benoemde kamer. Clients die dezelfde naam openen, ontvangen elkaars berichten. De client maakt vanzelf verbinding wanneer u zich abonneert.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// 'GEABONNEERD' | 'KANAAL_ERROR' | 'TIMED_OUT' | 'GESLOTEN'
if (status === 'SUBSCRIBED') console.log('ready')
})
Alleen verzenden na SUBSCRIBED. Voordien, of na een weigering, retourneert send() een status zoals not_connected of requires_subscription in plaats van te verzenden. Kanalen zijn afgestemd op uw project: twee projecten kunnen dezelfde naam gebruiken zonder elkaar te zien.
Berichten uitzenden#
// Ontvang
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // {gebeurtenis: 'ping', n: 1, tekst: 'hallo' }
})
// Verzenden, zodra u zich abonneert
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'oké'
In een echte run ontving een tweede ingelogde client het bericht binnen twee seconden.
Aan het bericht dat u ontvangt, is de gebeurtenisnaam toegevoegd aan payload: { "event": "ping", "n": 1, … }. Een payload met een eigen event-sleutel wordt geweigerd (channel.send retourneert 'invalid_payload', httpBroadcast retourneert realtime_payload_event_reserved): hernoem de sleutel, bijvoorbeeld kind.
- Je ontvangt standaard niet je eigen berichten. Open het kanaal met
{ config: { broadcast: { self: true } } }om ze te ontvangen. - Een bericht bevat
id,topic,timestamp,eventenpayload.
Aanwezigheid#
Aanwezigheid laat zien wie verbonden is met een kanaal, met een door u gekozen 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() wordt gecodeerd op gebruikers-ID. Bij elk item worden de verbindingen van de gebruiker vermeld:
{
"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() verwijdert je uit de lijst, en het verlaten van het kanaal of het sluiten van de pagina doet dat voor je.
Databasewijzigingen#
postgres_changes werkt aan projecten met een eigen database. Schakel eerst elke tabel in: PUT /v1/db/schema/tables/{table}/realtime (of aura db table realtime <table> on) met de hoofdtekst {"enabled": true} en een service_role sleutel. Het luisteren begint wanneer de eerste klant zich abonneert en stopt een paar minuten nadat de laatste is vertrokken. De levering vindt minimaal één keer plaats: na een herstart van de server kan een wijziging twee keer binnenkomen, dus maak uw handler idempotent, bijvoorbeeld door de primaire sleutel van de rij in te toetsen. Een bezet cluster kan een nieuwe luisteraar met een capaciteitsfout weigeren; probeer het binnenkort opnieuw. Elke kanaalnaam werkt: de table van elk filter selecteert de tabel waarnaar moet worden geluisterd, en één kanaal kan naar meerdere tabellen luisteren. Op een kanaal dat niet de naam db:<schema>.<table> heeft, heeft elk filter een table nodig. De eerste abonnee kan maximaal 5 seconden aan wijzigingen ontvangen die zijn aangebracht vlak voordat hij zich heeft geabonneerd. Wijzigingen worden één uur bewaard voor herstel en vervolgens verwijderd. Wanneer het cluster vol is, mislukt het abonnement met capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Als het luisteren langer dan een minuut uitblijft, gaat het kanaal naar CHANNEL_ERROR en vervolgens terug naar SUBSCRIBED zodra het luisteren is hersteld; U hoeft zich niet opnieuw te abonneren. Als een storing langer duurt dan de retentie van één uur, ontvangt het kanaal ook CHANNEL_ERROR met changements postgres_changes perdus pendant l'interruption, resynchronisez: laad de gegevens opnieuw uit de database. Een wijziging behoudt elke keer dat deze wordt afgeleverd dezelfde id, dus u kunt ook een id overslaan die u al hebt afgehandeld. De rij van een verwijdering bestaat niet meer, dus de beveiliging op rijniveau kan hierop niet worden geëvalueerd. Op een tabel met beveiliging op rijniveau wordt een DELETE daarom alleen geleverd aan abonnees wier rol een SELECT-beleid op de tafel heeft (of RLS omzeilt, zoals service_role): een bezoeker (anon) zonder leesbeleid ontvangt deze niet. Op een tafel zonder beveiliging op rijniveau ontvangt elke abonnee dit. payload.old van een DELETE bevat alleen de primaire sleutelkolommen (niets als de tabel geen primaire sleutel heeft), en een filter op een andere kolom komt nooit overeen met een verwijdering. Voor een UPDATE bevat payload.old ook alleen de primaire sleutelkolommen van de vorige rij (hun vorige waarden als de sleutel is gewijzigd), nooit de andere waarden: de beveiliging op rijniveau wordt alleen op de nieuwe rij gecontroleerd. Het filter van een UPDATE is van toepassing op de nieuwe rij. Houd gevoelige informatie uit de primaire sleutels.
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')
})
Opruimen#
room.unsubscribe() // laat één kanaal achter
aura.realtime.removeChannel(room) // vertrek en vergeet het
aura.realtime.removeAllChannels() // verlaat elk kanaal
aura.realtime.disconnect() // sluit de verbinding
Bekijk de verbinding met aura.realtime.onStateChange(callback) en onError(callback). Na een onderbreking maakt de client vanzelf opnieuw verbinding, tenzij u setAutoReconnect(false) aanroept.