Canais de cache

Um canal de cache guarda o evento mais recente e o reenvia para cada novo assinante. Um cliente que se conecta após uma atualização pode renderizar o estado atual sem esperar por outra publicação.

Use canais de cache para valores atuais como placar de uma partida, estado de dispositivo, progresso de build ou status de pedido. A assinatura fornece o estado inicial e as atualizações posteriores.

Nomeie um canal de cache

O nome do canal habilita o cache. Coloque cache- no início do nome ou logo após o prefixo de tipo do canal.

Nome	Cache	Assinatura
cache-orders	sim	qualquer um com a chave do app
private-cache-orders	sim	seu backend assina pelo cliente
presence-cache-lobby	sim	seu backend assina, membros rastreados
orders-cache	não	qualquer um com a chave do app

orders-cache não é um canal de cache. O prefixo cache- deve vir antes do nome, após qualquer prefixo private- ou presence-.

Todo o restante do canal permanece inalterado. Um canal private-cache- autoriza exatamente como um canal privado, e um canal presence-cache- continua rastreando membros e disparando eventos de membros como qualquer outro canal de presença.

Assinatura

const bird = new BirdRealtime({ appKey: "your-app-key", region: "us1" });

const match = bird.subscribe("cache-match-42");

match.bind("score-updated", (data) => {
  render(data);
});

match.bind("bird:cache_miss", () => {
  console.log("nothing cached for this channel yet");
});

let bird = BirdRealtime(options: .init(appKey: "your-app-key", region: "us1"))

let match = bird.subscribe("cache-match-42")

match.bind("score-updated") { data in
    render(data)
}

match.bind("bird:cache_miss") { _ in
    print("nothing cached for this channel yet")
}

val bird = BirdRealtime(BirdRealtimeOptions(appKey = "your-app-key", region = "us1"))

val match = bird.subscribe("cache-match-42")

match.bind("score-updated") { data ->
    render(data)
}

match.bind("bird:cache_miss") {
    println("nothing cached for this channel yet")
}

Em caso de acerto, o evento em cache chega após a assinatura ser bem-sucedida. Ele traz o nome e o payload do evento original, então o mesmo handler processa eventos em cache e ao vivo.

Em caso de falha, o cliente recebe bird:cache_miss naquele canal. Ou o canal nunca recebeu uma publicação ou o evento em cache expirou.

Preenchendo o cache em caso de falha

Se um endpoint assina realtime.cache_channels, a falha também chega ao seu servidor. Trate o webhook lendo o estado atual e publicando-o no canal.

await bird.realtime.publish(appId, {
  event: "score-updated",
  channels: ["cache-match-42"],
  data: await currentScore(42),
});

client.realtime.publish(
    app_id,
    event="score-updated",
    channels=["cache-match-42"],
    data=current_score(42),
)

_, err := client.Realtime.Publish(context.Background(), appID, bird.RealtimePublishParams{
	Event:    "score-updated",
	Channels: []string{"cache-match-42"},
	Data:     currentScore(42),
})

$bird->realtime->publish($appId, (new RealtimePublish())
    ->setEvent('score-updated')
    ->setChannels(['cache-match-42'])
    ->setData(currentScore(42)));

O cliente que causou a falha já está inscrito antes de o servidor publicar o evento substituto, então ele recebe o novo estado. Esse fluxo também preenche um cache vazio para o primeiro assinante.

Conteúdo e retenção do cache

Eventos publicados pela API são armazenados em cache, incluindo publicações únicas e em lote. Eventos de cliente cujos nomes começam com client- não são armazenados em cache.

Eventos em cache podem permanecer disponíveis por até 30 minutos, mas podem expirar antes. Repopule canais atualizados com pouca frequência a partir do webhook de cache-miss em vez de assumir que o cache ainda está ativo.

Cada canal guarda apenas o evento mais recente. Se você publicar score-updated e depois match-ended, um novo assinante receberá apenas match-ended. Use um nome de evento por canal de cache ou inclua o estado completo em cada payload.

Limitações do cache

Um canal de cache armazena apenas o evento mais recente. Ele não preserva um histórico de eventos. Um cliente que perde duas atualizações enquanto está offline recebe o estado mais recente sem o evento intermediário. Mantenha o estado durável no seu banco de dados. Após reconectar, o cliente se reinscreve e renderiza o evento em cache, caso ainda esteja disponível. Consulte Publicação de eventos para garantias de entrega.

Próximos passos

Publicação de eventos aborda publicação a partir do seu servidor, envio em lote e broadcasting.
Canais privados e Canais de presença se combinam com cache- no mesmo nome.
Consulta do estado do canal lê ocupação e contagens a partir do seu servidor.

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Explore a funcionalidadeRealtime Siga o percurso de aprendizagemBuild your first integration Guia de implementaçãoSend your first realtime event

Experimente na prática e obtenha um resumo de implementação