Canais Realtime

Um canal é um nome. Nada para provisionar.

Um canal existe assim que algo se inscreve nele e desaparece quando a última conexão sai. O nome define o tipo: público para tudo que um visitante pode ler, privado para tudo com escopo de um cliente, presença para uma sala com lista de membros e um prefixo de cache para estado que um participante tardio precisa imediatamente.

channels.ts

4 subscribed

const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" });

// Public: anyone holding the app key can subscribe.
const scores = bird.subscribe("match-42");

// Private: your backend signs every subscription.
const order = bird.subscribe("private-order-ord_123");

// Presence: private, plus an identity the room can see.
const room = bird.subscribe("presence-room-42");

// Cache: the latest event replays to whoever joins next.
const build = bird.subscribe("cache-build-8821");

build.bind("bird:cache_miss", () => showSkeleton());

channels.ts

4 subscribed

const bird = new BirdRealtime({ appKey: APP_KEY, region: "us1" });

// Public: anyone holding the app key can subscribe.
const scores = bird.subscribe("match-42");

// Private: your backend signs every subscription.
const order = bird.subscribe("private-order-ord_123");

// Presence: private, plus an identity the room can see.
const room = bird.subscribe("presence-room-42");

// Cache: the latest event replays to whoever joins next.
const build = bird.subscribe("cache-build-8821");

build.bind("bird:cache_miss", () => showSkeleton());

O prefixo é a configuração.

Não há registro de canais para manter sincronizado.

Os canais são o modelo de endereçamento da Bird Realtime API. Você nunca cria um: você se inscreve em um nome, e os três primeiros caracteres desse nome dizem ao edge como tratá-lo. Um nome sem prefixo é público. private- solicita que seu backend aprove cada inscrição. presence- faz o mesmo e anexa uma identidade. private-encrypted- sela o payload com uma chave que Bird nunca possui. Os nomes aceitam até 164 caracteres, diferenciam maiúsculas de minúsculas e são a única parte de um canal sobre a qual você deve pensar com cuidado, porque um nome público é visível para qualquer pessoa que possua a chave do app.

Cinco tipos de sala.

Mesmo protocolo, mesmo cliente, mesma chamada de publicação. O nome é o que difere.

01
Canais públicos.
Sem endpoint de autorização, sem registro. Qualquer pessoa com a chave do app pode se inscrever, o que os torna ideais para resultados de builds, placares ao vivo, informações de voos ou uma página de status — e inadequados para qualquer coisa com escopo de um único cliente. Mantenha identificadores fora do nome: orders não revela nada, orders-user-4821 revela que o usuário 4821 existe.
02
Canais privados.
Um nome private- encaminha a inscrição pelo seu próprio endpoint, que verifica a sessão e assina o ID da conexão e o nome do canal com o segredo do app. Suas regras, sua sessão, seu 403. O edge verifica a assinatura e nada mais chega ao canal.
03
Canais de presença.
Autorização de canal privado mais uma identidade, para que cada inscrito receba a lista de membros e seja notificado sobre chegadas e saídas. Este é o único tipo de canal com uma lista de participantes.
04
Canais encriptados.
Um canal private-encrypted- transporta payloads que seu servidor sela com uma chave mestra de 32 bytes que nunca aparece em uma requisição Realtime. O edge e tudo entre ele e o navegador veem texto cifrado. Nomes de canais e eventos permanecem em texto claro, então escolha nomes que não revelem o que você está protegendo.
05
Canais em cache.
Comece o nome com cache-, após qualquer prefixo de tipo, e o canal lembrará seu último evento publicado via API e o reproduzirá para cada novo inscrito. A inscrição funciona também como a busca do estado inicial. Duas restrições que vale considerar no design: apenas o evento mais recente é mantido, e ele pode expirar antes do limite de 30 minutos — então coloque o estado completo em cada payload e repopule a partir do webhook de cache-miss em vez de assumir que o cache está ativo.

Uma publicação, até cem canais.

Publicar é uma chamada REST comum do seu servidor. Nomeie até 100 canais em uma requisição e o edge distribui o evento para todos eles. Um lote comporta até 10 eventos independentes, cada um para seu próprio canal. Passe o ID de conexão do cliente atuante como exclude_connection_id e a aba que já aplicou a mudança localmente será ignorada. Solicite contagens de conexões ou membros com include e a resposta informa o estado de cada canal no momento da publicação. Tente novamente com a mesma chave de idempotência e você não entregará duas vezes.

publish.ts

200 · accepted

// One event, up to 100 channels, one request.
const result = await bird.realtime.publish(APP_ID, {
  event: "score-updated",
  channels: ["match-42", "cache-match-42"],
  data: { home: 2, away: 1 },
  // The tab that scored already rendered it locally.
  exclude_connection_id: "26896.319537",
  include: ["connection_count"],
});

for (const channel of result.data ?? []) {
  console.log(channel.name, channel.connection_count);
}

Os clientes podem se comunicar diretamente entre si.

Um indicador de digitação ou uma posição de cursor não precisa passar pela sua API. Ative eventos de cliente no app e um cliente inscrito pode disparar um evento chamado client-algo diretamente para os outros no canal, limitado a 10 por segundo por conexão. Eles só funcionam em canais privados e de presença, e isso é intencional: a chave do app está na sua página, então a autorização é o que torna um cliente confiável o suficiente para transmitir. Trate o que chega como um sinal, nunca como estado autoritativo, porque o edge não valida o payload.

O que um canal vai e não vai lembrar.

Uma publicação retorna assim que o edge aceita o evento. A entrega é assíncrona, não há confirmação por cliente, e um cliente que cai no meio da entrega não receberá o evento novamente ao reconectar. Esse é o contrato honesto, e é por isso que estado durável pertence ao seu banco de dados e os eventos anunciam que ele mudou. Os limites são os mesmos em todos os planos: 100 canais por publicação, 10 eventos por lote, 10 KB por payload, nomes de canal de 164 caracteres.

Aprofunde-se na documentação.

A visão geral do Realtime define canais, membros e conexões em uma única página. Publicação de eventos abrange broadcast, lote e exclusão, canais em cache explica a reprodução, e consulta de estado do canal é a leitura server-side para ocupação e contagens.