Envie mensagens ao vivo e presença com o JavaScript SDK
Os fluxos diários de aura.realtime, com o comportamento de cada chamada observado em uma pilha em execução.
Canais e seu status#
Um canal é uma sala nomeada. Os clientes que abrem o mesmo nome recebem mensagens uns dos outros. O cliente se conecta sozinho quando você se inscreve.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// 'ASSINADO' | 'CHANNEL_ERROR' | 'TIMED_OUT' | 'FECHADO'
if (status === 'SUBSCRIBED') console.log('ready')
})
Envie somente após SUBSCRIBED. Antes disso, ou após uma recusa, send() retorna um status como not_connected ou requires_subscription em vez de enviar. Os canais têm como escopo o seu projeto: dois projetos podem usar o mesmo nome sem se verem.
Transmitir mensagens#
// Receber
room.on('broadcast', { event: 'ping' }, (message) => {
console.log(message.payload) // {evento: 'ping', n: 1, texto: 'olá' }
})
// Enviar, uma vez ASSINADO
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'ok'
Em uma execução real, um segundo cliente conectado recebeu a mensagem em menos de dois segundos.
A mensagem que você recebe tem o nome do evento adicionado a payload: { "event": "ping", "n": 1, … }. Uma carga útil que possui sua própria chave event é recusada (channel.send retorna 'invalid_payload', httpBroadcast retorna realtime_payload_event_reserved): renomeie a chave, por exemplo kind.
- Você não recebe suas próprias mensagens por padrão. Abra o canal com
{ config: { broadcast: { self: true } } }para recebê-los. - Uma mensagem carrega
id,topic,timestamp,eventepayload.
Presença#
A presença mostra quem está conectado a um canal, com um estado que você escolher.
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() é digitado pelo ID do usuário. Cada entrada lista as conexões do usuário:
{
"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() remove você da lista, e sair do canal ou fechar a página faz isso por você.
Mudanças no banco de dados#
postgres_changes trabalha em projetos com banco de dados próprio. Habilite cada tabela primeiro: PUT /v1/db/schema/tables/{table}/realtime (ou aura db table realtime <table> on) com o corpo {"enabled": true} e uma chave service_role. A escuta começa quando o primeiro cliente se inscreve e termina alguns minutos após a saída do último. A entrega ocorre pelo menos uma vez: após a reinicialização do servidor, uma alteração pode chegar duas vezes, portanto, torne seu manipulador idempotente, por exemplo, digitando a chave primária da linha. Um cluster ocupado pode recusar um novo ouvinte com erro de capacidade; tente novamente em breve. Qualquer nome de canal funciona: table de cada filtro seleciona a tabela a ser escutada e um canal pode escutar várias tabelas. Em um canal que não é nomeado db:<schema>.<table>, todo filtro precisa de um table. O primeiro assinante pode receber até 5 segundos de alterações feitas antes de se inscrever. As alterações são mantidas por uma hora para recuperação e depois excluídas. Quando o cluster estiver cheio, a assinatura falhará com capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Se a escuta permanecer desligada por mais de um minuto, o canal passará para CHANNEL_ERROR e voltará para SUBSCRIBED assim que a escuta for restaurada; você não precisa se inscrever novamente. Se uma interrupção durar mais que a retenção de uma hora, o canal também receberá CHANNEL_ERROR com changements postgres_changes perdus pendant l'interruption, resynchronisez: recarregue os dados do banco de dados. Uma alteração mantém o mesmo id cada vez que é entregue, portanto, você também pode pular um id que já administrou. A linha de uma exclusão não existe mais, portanto a segurança em nível de linha não pode ser avaliada nela. Em uma tabela com segurança em nível de linha, um DELETE é, portanto, entregue apenas aos assinantes cuja função tem uma política SELECT na tabela (ou ignora RLS, como service_role): um visitante (anon) sem uma política de leitura não o recebe. Em uma tabela sem segurança em nível de linha, todos os assinantes a recebem. payload.old de um DELETE contém apenas as colunas de chave primária (nada se a tabela não tiver chave primária) e um filtro em qualquer outra coluna nunca corresponde a uma exclusão. Para um UPDATE, payload.old também contém apenas as colunas de chave primária da linha anterior (seus valores anteriores se a chave for alterada), nunca seus outros valores: a segurança em nível de linha é verificada apenas na nova linha. O filtro de UPDATE se aplica à nova linha. Mantenha informações confidenciais fora das chaves primárias.
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')
})
Limpar#
room.unsubscribe() // sair de um canal
aura.realtime.removeChannel(room) // vá embora e esqueça
aura.realtime.removeAllChannels() // sair de todos os canais
aura.realtime.disconnect() // feche a conexão
Observe a conexão com aura.realtime.onStateChange(callback) e onError(callback). Após uma queda, o cliente se reconecta sozinho, a menos que você chame setAutoReconnect(false).