Saltar al contenido
Logotipo de Aurabase
aurabase

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.

Guía práctica7 min leerNivel intermedioRevisado el 12 oct 2026

Esta página fue traducida automáticamente. La versión en inglés es autorizada.

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í.

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 tiene el nombre del evento agregado a payload: { "event": "ping", "n": 1, … }. Se rechaza una carga útil que tiene 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#

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 en la base de datos#

Proyectos con base de datos propia

postgres_changes trabaja en proyectos con su propia base de datos. Habilite cada tabla primero: PUT /v1/db/schema/tables/{table}/realtime (o aura db table realtime <table> on) con el cuerpo {"enabled": true} y una clave service_role. La escucha comienza cuando el primer cliente se suscribe y se detiene unos minutos después de que el último se vaya. La entrega es al menos una vez: después de reiniciar el servidor, un cambio puede llegar dos veces, así que haga que su controlador sea idempotente, por ejemplo ingresando la clave principal de la fila. Un clúster ocupado puede rechazar un nuevo oyente con un error de capacidad; Vuelva a intentarlo en breve. Cualquier nombre de canal funciona: el table de cada filtro selecciona la tabla a escuchar y un canal puede escuchar varias tablas. En un canal que no se llama db:<schema>.<table>, cada filtro necesita un table. El primer suscriptor puede recibir hasta 5 segundos de los cambios realizados justo antes de suscribirse. Los cambios se conservan durante una hora para su 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 permanece inactiva durante más de un minuto, el canal pasa a CHANNEL_ERROR y luego regresa a SUBSCRIBED una vez que se restablece la escucha; no es necesario suscribirse nuevamente. Si una interrupción dura más que la retención de una hora, el canal también recibe CHANNEL_ERROR con changements postgres_changes perdus pendant l'interruption, resynchronisez: recarga los datos de la base de datos. Un cambio mantiene el mismo id cada vez que se entrega, por lo que también puedes omitir un id que ya hayas manejado. La fila de una eliminación ya no existe, por lo que no se puede evaluar la seguridad a nivel de fila en ella. En una tabla con seguridad a nivel de fila, un DELETE se entrega solo a los suscriptores cuyo rol tiene una política SELECT en la tabla (o pasa por alto RLS, como service_role): un visitante (anon) sin una política de lectura no la recibe. En una mesa sin seguridad a nivel de fila, cada suscriptor la recibe. payload.old de un DELETE contiene solo las columnas de clave principal (nada si la tabla no tiene clave principal), y un filtro en cualquier otra columna nunca coincide con una eliminación. Para un UPDATE, payload.old también contiene solo las columnas de clave principal de la fila anterior (sus valores anteriores si la clave cambió), nunca sus otros valores: la seguridad a nivel de fila se verifica solo en la nueva fila. El filtro de un UPDATE se aplica a la nueva fila. Mantenga la información confidencial fuera de las claves primarias.

changes.tstypescript
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')
  })

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