Aura Logo
aurabasedocumentos
documentos›Guias›Realtime and presence (SDK)

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.

7 min lido·Nível intermediário·Revisado em 12 de out. de 2026
Este texto em inglês foi gerado automaticamente a partir do original em francês e ainda não foi revisado.
A fonte em inglês mudou desde esta tradução. Algumas informações podem estar desatualizadas.
Esta página foi traduzida automaticamente. A versão em inglês é oficial.
#
Canais

1. Canais e seus 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.

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

2. Transmitir mensagens

broadcast.tstypescript
// 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 carga útil carrega uma chave event

A mensagem recebida traz o nome do evento adicionado ao payload: { "event": "ping", "n": 1, … }. Um payload que tenha sua própria chave event é recusado (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, event e payload.
#
Presença

3. Presença

A presença mostra quem está conectado a um canal, com um estado que você escolher.

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() é digitado pelo ID do usuário. Cada entrada lista as conexões do usuário:

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() remove você da lista, e sair do canal ou fechar a página faz isso por você.

#
Mudanças

4. Mudanças no banco de dados

Projetos com banco de dados próprio

postgres_changes funciona em projetos que têm banco de dados próprio. Ative cada tabela primeiro: PUT /v1/db/{project_id}/schema/tables/{table}/realtime com o corpo {"enabled": true} e uma chave service_role. A escuta começa quando o primeiro cliente se inscreve e para alguns minutos depois que o último sai. A entrega é pelo menos uma vez: após um reinício do servidor, uma alteração pode chegar duas vezes, então torne seu manipulador idempotente, por exemplo usando a chave primária da linha. Um cluster ocupado pode recusar uma nova escuta com um erro de capacidade; tente novamente em instantes. Dê ao canal o nome da tabela, db:public.<table>: é nesse canal que as alterações são publicadas. O primeiro assinante pode receber até 5 segundos de alterações feitas pouco antes da assinatura. As alterações são mantidas por uma hora para a retomada e depois apagadas. Quando o cluster está cheio, a assinatura falha com capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Se a escuta continuar perdida por mais de um minuto, o canal passa para CHANNEL_ERROR; assine de novo quando ela voltar. Uma interrupção mais longa que a hora de retenção perde as alterações feitas durante ela.

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

5. Limpe

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

Última atualização · 12 de out. de 2026