Logotipo de Aurabase
aurabasedocumentos
documentos›Guías›Realtime and presence (SDK)

Envía mensajes en vivo y presencia con el SDK de JavaScript

Los flujos cotidianos de aura.realtime, con el comportamiento de cada llamada observado en una pila en ejecución.

7 min leer·Nivel intermedio·Revisado el 12 oct 2026
Este texto en inglés se generó automáticamente a partir del original en francés y aún no ha sido revisado.
La fuente en inglés ha cambiado desde esta traducción. Es posible que parte de la información esté desactualizada.
Esta página fue traducida automáticamente. La versión en inglés es autorizada.
#
Canales

1. Canales y su estado

Un canal es una sala con nombre. Los clientes que abren el mismo nombre reciben los mensajes de los demás. El cliente se conecta solo cuando te suscribes.

channel.tstypescript
const room = aura.realtime.channel('room-1')

room.subscribe((status) => {
  // 'SUSCRIBIDO' | 'CANAL_ERROR' | 'TIMED_OUT' | 'CERRADO'
  if (status === 'SUBSCRIBED') console.log('ready')
})

Enviar solo después de SUBSCRIBED. Antes de eso, o después de un rechazo, send() devuelve un estado como not_connected o requires_subscription en lugar de enviar. Los canales tienen como ámbito su proyecto: dos proyectos pueden usar el mismo nombre sin verse entre sí.

#
Difusión

2. Mensajes de difusión

broadcast.tstypescript
// Recibir
room.on('broadcast', { event: 'ping' }, (message) => {
  console.log(message.payload) // { evento: 'ping', n: 1, texto: 'hola' }
})

// Enviar, una vez SUSCRITO
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'bien'

En una ejecución real, un segundo cliente que inició sesión recibió el mensaje en menos de dos segundos.

La carga útil lleva una clave event

El mensaje que recibe lleva el nombre del evento añadido al payload: { "event": "ping", "n": 1, … }. Se rechaza un payload que tenga su propia clave event (channel.send devuelve 'invalid_payload', httpBroadcast devuelve realtime_payload_event_reserved): cambie el nombre de la clave, por ejemplo kind.

  • No recibes tus propios mensajes de forma predeterminada. Abre el canal con { config: { broadcast: { self: true } } } para recibirlos.
  • Un mensaje transporta id, topic, timestamp, event y payload.
#
Presencia

3. Presencia

Presencia muestra quién está conectado a un canal, con un estado que elijas.

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() está codificado por ID de usuario. Cada entrada enumera las conexiones del usuario:

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() te elimina de la lista y dejar el canal o cerrar la página lo hace por ti.

#
Cambios

4. Cambios en la base de datos

Proyectos con su propia base de datos

postgres_changes funciona en los proyectos que tienen su propia base de datos. Active primero cada tabla: PUT /v1/db/{project_id}/schema/tables/{table}/realtime con el cuerpo {"enabled": true} y una clave service_role. La escucha empieza cuando se suscribe el primer cliente y se detiene unos minutos después de que se vaya el último. La entrega es al menos una vez: tras un reinicio del servidor, un cambio puede llegar dos veces, así que haga que su manejador sea idempotente, por ejemplo usando la clave primaria de la fila. Un clúster ocupado puede rechazar una nueva escucha con un error de capacidad; vuelva a intentarlo en breve. Nombre el canal según la tabla, db:public.<table>: los cambios se publican en ese canal. El primer suscriptor puede recibir hasta 5 segundos de cambios hechos justo antes de suscribirse. Los cambios se conservan una hora para la recuperación y luego se eliminan. Cuando el clúster está lleno, la suscripción falla con capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Si la escucha sigue perdida más de un minuto, el canal pasa a CHANNEL_ERROR; vuelva a suscribirse cuando se restablezca. Una interrupción más larga que la hora de retención pierde los cambios hechos durante ella.

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')
  })
#
limpieza

5. Limpiar

cleanup.tstypescript
room.unsubscribe()                 // dejar un canal
aura.realtime.removeChannel(room)  // déjalo y olvídalo
aura.realtime.removeAllChannels()  // dejar todos los canales
aura.realtime.disconnect()         // cerrar la conexión

Mire la conexión con aura.realtime.onStateChange(callback) y onError(callback). Después de una caída, el cliente se vuelve a conectar solo a menos que llame a setAutoReconnect(false).

Última actualización · 12 oct 2026