Invia messaggi in tempo reale e presenza con l'SDK JavaScript
I flussi quotidiani di aura.realtime, con il comportamento di ogni chiamata osservato rispetto a uno stack in esecuzione.
Canali e loro stato#
Un canale è una stanza con nome. I client che aprono lo stesso nome ricevono i reciproci messaggi. Il client si connette da solo quando ti iscrivi.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// 'SOTTOSCRITTO' | 'ERRORE_CANALE' | 'TEMPO_OUT' | 'CHIUSO'
if (status === 'SUBSCRIBED') console.log('ready')
})
Invia solo dopo SUBSCRIBED. Prima di ciò, o dopo un rifiuto, send() restituisce uno stato come not_connected o requires_subscription invece di inviare. I canali hanno come ambito il tuo progetto: due progetti possono utilizzare lo stesso nome senza vedersi.
Trasmettere messaggi#
// Ricevi
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // { evento: 'ping', n: 1, testo: 'ciao' }
})
// Invia, una volta SOTTOSCRITTO
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'ok'
In un'esecuzione reale, un secondo client connesso ha ricevuto il messaggio in meno di due secondi.
Il messaggio che ricevi ha il nome dell'evento aggiunto a payload: { "event": "ping", "n": 1, … }. Un payload che ha la propria chiave event viene rifiutato (channel.send restituisce 'invalid_payload', httpBroadcast restituisce realtime_payload_event_reserved): rinominare la chiave, ad esempio kind.
- Per impostazione predefinita non ricevi i tuoi messaggi. Apri il canale con
{ config: { broadcast: { self: true } } }per riceverli. - Un messaggio trasporta
id,topic,timestamp,eventepayload.
Presenza#
La presenza mostra chi è connesso a un canale, con uno stato scelto da te.
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() è codificato dall'ID utente. Ogni voce elenca le connessioni dell'utente:
{
"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() ti rimuove dall'elenco e l'abbandono del canale o la chiusura della pagina lo fanno per te.
Modifiche alla banca dati#
postgres_changes lavora su progetti con il proprio database. Abilita prima ciascuna tabella: PUT /v1/db/schema/tables/{table}/realtime (o aura db table realtime <table> on) con il corpo {"enabled": true} e una chiave service_role. L'ascolto inizia quando il primo cliente si iscrive e si interrompe pochi minuti dopo l'uscita dell'ultimo. La consegna avviene almeno una volta: dopo il riavvio del server una modifica può arrivare due volte, quindi rendi il tuo gestore idempotente, ad esempio digitando la chiave primaria della riga. Un cluster occupato può rifiutare un nuovo ascoltatore con un errore di capacità; riprovare a breve. Funziona qualsiasi nome di canale: table di ciascun filtro seleziona la tabella da ascoltare e un canale può ascoltare più tabelle. Su un canale che non si chiama db:<schema>.<table>, ogni filtro necessita di un table. Il primo abbonato può ricevere fino a 5 secondi di modifiche apportate subito prima dell'iscrizione. Le modifiche vengono conservate per un'ora per il ripristino, quindi eliminate. Quando il cluster è pieno, la sottoscrizione fallisce con capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Se l'ascolto rimane inattivo per più di un minuto, il canale si sposta su CHANNEL_ERROR, per poi tornare su SUBSCRIBED una volta ripristinato l'ascolto; non è necessario abbonarsi nuovamente. Se un'interruzione supera l'ora di conservazione, il canale riceve anche CHANNEL_ERROR con changements postgres_changes perdus pendant l'interruption, resynchronisez: ricarica i dati dal database. Una modifica mantiene lo stesso id ogni volta che viene consegnata, quindi puoi anche saltare un id che hai già gestito. La riga di un'eliminazione non esiste più, pertanto non è possibile valutarne la sicurezza a livello di riga. Su una tabella con sicurezza a livello di riga, un DELETE viene quindi consegnato solo ai sottoscrittori il cui ruolo ha una policy SELECT sulla tabella (o ignora RLS, come service_role): un visitatore (anon) senza una policy di lettura non lo riceve. Su una tabella senza sicurezza a livello di riga ogni abbonato lo riceve. payload.old di un DELETE contiene solo le colonne della chiave primaria (niente se la tabella non ha una chiave primaria) e un filtro su qualsiasi altra colonna non corrisponde mai a un'eliminazione. Per un UPDATE, payload.old contiene anche solo le colonne della chiave primaria della riga precedente (i loro valori precedenti se la chiave è cambiata), mai gli altri valori: la sicurezza a livello di riga viene verificata solo sulla nuova riga. Il filtro di un UPDATE si applica alla nuova riga. Mantieni le informazioni sensibili fuori dalle chiavi primarie.
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')
})
Pulisci#
room.unsubscribe() // lasciare un canale
aura.realtime.removeChannel(room) // vai via e dimenticalo
aura.realtime.removeAllChannels() // abbandonare ogni canale
aura.realtime.disconnect() // chiudere la connessione
Guarda la connessione con aura.realtime.onStateChange(callback) e onError(callback). Dopo una caduta, il client si riconnette da solo a meno che non chiami setAutoReconnect(false).