Visão geral do Realtime
O Realtime envia eventos para clientes conectados por WebSockets. Seu servidor publica um evento em um canal nomeado, e os clientes inscritos o recebem sem polling.
Use o Realtime para mudanças que o cliente precisa sem fazer outra solicitação, como atualizações de pedidos, mensagens de chat, alterações em dashboards ou jobs em segundo plano concluídos.
Canais, membros e conexões
Três palavras descrevem o modelo. Elas não são intercambiáveis.
Um channel é uma sala nomeada. Ele existe enquanto pelo menos uma conexão está inscrita e desaparece quando a última sai. Nomes de canal permitem até 164 letras, dígitos e estes caracteres: _ - = @ , . ;.
Uma connection é um WebSocket aberto. Ela recebe um ID (26896.319537) ao se conectar. A autorização assina esse ID, e a publicação pode excluí-lo da entrega.
Um member é uma identidade autenticada em um canal de presença. Um membro pode ter várias conexões, como três abas do navegador. Eventos de presença disparam quando a primeira conexão do membro entra e quando a última sai. Abas intermediárias não os produzem.
Os três tipos de canal
O prefixo do nome do canal seleciona o tipo de canal e seu comportamento de autorização.
| Nome | Quem pode se inscrever | Tem membros |
|---|---|---|
| orders | qualquer pessoa com a app key | não |
| private-orders | apenas clientes assinados pelo seu backend | não |
| presence-lobby | apenas clientes assinados pelo seu backend | sim |
Um canal public pode ser lido por qualquer pessoa com a app key, que é distribuída no código do cliente. Publique apenas dados que qualquer visitante possa ver. Veja Canais públicos.
Um canal private exige que seu backend aprove cada inscrição. O cliente envia o ID da conexão e o nome do canal para o seu endpoint, que retorna uma assinatura calculada com o app secret. Veja Canais privados. Um canal private-encrypted-… também criptografa payloads com uma chave mantida nos seus servidores. Veja Canais criptografados.
Um canal presence adiciona uma identidade à autorização de canal privado. Cada inscrito recebe a lista de membros e as alterações por meio de member_id e opcionalmente member_info. Veja Canais de presença.
Eventos que o cliente recebe
Eventos de aplicação são seus: você escolhe o nome no momento da publicação (order-updated, message.created) e associa um handler a ele. Junto com eles, o cliente reemite eventos de ciclo de vida sob o prefixo bird:, que você associa exatamente como os seus:
- bird:subscription_succeeded dispara uma vez por canal quando a inscrição está ativa. Em um canal de presença, ele traz a lista atual de membros, para que você possa renderizar a sala antes de qualquer movimentação.
- bird:member_added e bird:member_removed disparam em canais de presença quando membros chegam e saem. member_added dispara quando a primeira conexão de uma pessoa se inscreve; member_removed apenas quando a última sai. Uma segunda aba abrindo e fechando não produz nenhum dos dois.
- bird:connection_count informa quantas conexões estão inscritas no canal, se o app tiver contagem de conexões e eventos de contagem de conexões habilitados. Ele conta conexões, então o membro com três abas conta três.
- bird:subscription_error dispara quando uma inscrição é recusada, geralmente porque a autorização falhou.
Nomes que começam com client- são reservados para eventos que clientes enviam diretamente entre si, o que é uma configuração separada do app e permitido apenas em canais privados e de presença.
Seu servidor também pode receber eventos, como webhooks, quando um canal fica ocupado ou vazio e quando membros entram ou saem. Eles chegam como eventos realtime.* pelos mesmos endpoints de webhook do restante do Bird.
Os clientes
Três clientes recebem eventos pelo mesmo protocolo. Use @messagebird/realtime para navegadores e Node.js, BirdRealtime para iOS, macOS e Linux, ou com.messagebird:bird-realtime para Android e a JVM do servidor. Cada um suporta inscrições, bindings, presença, signin() e eventos de cliente.
Mantenha o app secret no seu servidor. SDKs de servidor o usam para publicar eventos, autorizar canais e desconectar membros.
Apps, keys e regiões
Um app é um ambiente isolado com suas próprias credenciais e seu próprio namespace de canais. Dois apps nunca enxergam os canais um do outro, e é isso que torna o app a fronteira certa entre seus ambientes de staging e produção.
Cada app usa uma região imutável selecionada na criação. Use Listar regiões do Realtime para recuperar os identificadores aceitos e escolha a região mais próxima dos seus usuários.
Cada app tem três valores com usos diferentes:
- O app ID (rap_…) identifica o app nas chamadas Bird API e aparece em cada path /v1/realtime/apps/….
- A key é pública. Navegadores se conectam com ela, e é seguro distribuí-la no código do cliente.
- O secret é pareado com a key para autenticar chamadas do lado do servidor e assinar a autorização de canal. Ele é exibido uma única vez, na criação. Qualquer pessoa que o possua pode publicar no seu app e forjar identidades de presença.
Gerencie apps e faça a rotação de keys na página Realtime apps. Crie uma segunda key, faça o deploy dela e então revogue a key antiga.
Visibilidade
A página Métricas do Realtime exibe três valores por app ou em todo o espaço de trabalho para a janela selecionada:
- Máximo de conexões é o maior número de conexões abertas ao mesmo tempo dentro da janela. Esse pico é o valor ao qual o limite de conexões se aplica.
- Média de conexões é a média dos picos diários. Não é a média de todas as amostras. Um espaço de trabalho que tem picos toda tarde e fica ocioso à noite mostra uma média bem acima das horas de baixa atividade.
- Mensagens conta entregas de eventos, uma por canal: uma publicação que nomeia 50 canais conta como 50. Também inclui os eventos que o protocolo envia em seu nome, então entradas de presença e atualizações de contagem de conexões ficam no mesmo número, razão pela qual ele pode ficar à frente das publicações que seu código fez.
O uso é agregado em intervalos de um minuto, então o tráfego recente pode levar vários minutos para aparecer. O API de uso está disponível apenas para o dashboard. Para visibilidade programática, registre as publicações nos seus sistemas ou derive a atividade dos webhooks realtime.*.
Planos e limites
O plano gratuito cobre 100 conexões simultâneas e 200.000 mensagens por dia, em todos os apps de um espaço de trabalho. Criar mais apps não aumenta o teto, porque ele se aplica ao espaço de trabalho.
Planos pagos começam em US$ 25 por mês para 250 conexões simultâneas e 500.000 mensagens por dia, e escalam até 30.000 conexões e 90 milhões de mensagens por dia. Preços do Realtime lista cada faixa.
Limites por solicitação se aplicam em todos os planos: uma publicação nomeia no máximo 100 canais, um batch carrega no máximo 10 eventos, e o payload de um evento é limitado a 10 KB serializados.
Próximos passos
- Envie seu primeiro evento realtime percorre o fluxo completo de ponta a ponta.
- Publicando eventos cobre a publicação a partir do seu servidor, batching e exclusão do cliente de origem.
- Autorizando canais é o contrato que seu backend implementa para canais privados e de presença.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.