Logo Aurabase
aurabasedocumenti
documenti›Guide›Realtime and presence (SDK)

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.

7 min letto·Livello intermedio·Revisionato il 12 ott 2026
Questo testo inglese è stato generato automaticamente dall'originale francese e non è stato ancora rivisto.
La fonte inglese è cambiata da questa traduzione. Alcune informazioni potrebbero non essere aggiornate.
Questa pagina è stata tradotta automaticamente. Fa fede la versione inglese.
#
Canali

1. Canali e loro status

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.

channel.tstypescript
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

2. Trasmettere messaggi

broadcast.tstypescript
// 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 carico utile trasporta una chiave event

Il messaggio ricevuto contiene il nome dell’evento aggiunto al payload: { "event": "ping", "n": 1, … }. Un payload con una propria chiave event viene rifiutato (channel.send restituisce 'invalid_payload', httpBroadcast restituisce realtime_payload_event_reserved): rinomina 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, event e payload.
#
Presenza

3. Presenza

La presenza mostra chi è connesso a un canale, con uno stato scelto.

presence.tstypescript
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:

presenceState()json
{
  "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.

#
Cambiamenti

4. Modifiche al database

Progetti con un proprio database

postgres_changes funziona sui progetti che hanno un proprio database. Attiva prima ogni tabella: PUT /v1/db/{project_id}/schema/tables/{table}/realtime con il corpo {"enabled": true} e una chiave service_role. L’ascolto inizia quando si iscrive il primo client e si ferma qualche minuto dopo l’uscita dell’ultimo. La consegna è almeno una volta: dopo un riavvio del server una modifica può arrivare due volte, quindi rendi idempotente il tuo gestore, ad esempio basandoti sulla chiave primaria della riga. Un cluster occupato può rifiutare un nuovo ascolto con un errore di capacità; riprova poco dopo. Assegna al canale il nome della tabella, db:public.<table>: le modifiche vengono pubblicate su quel canale. Il primo iscritto può ricevere fino a 5 secondi di modifiche fatte poco prima dell’iscrizione. Le modifiche sono conservate un’ora per la ripresa, poi eliminate. Quando il cluster è pieno, l’iscrizione fallisce con capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Se l’ascolto resta perso per più di un minuto, il canale passa a CHANNEL_ERROR; iscriviti di nuovo quando torna disponibile. Un’interruzione più lunga dell’ora di conservazione perde le modifiche fatte nel frattempo.

changes.tstypescript
const changes = aura.realtime
  .channel('db:public.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')
  })
#
Pulizia

5. Pulisci

cleanup.tstypescript
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).

Ultimo aggiornamento · 12 ott 2026