Arquitetura avançada do Co-browse: presença ao vivo, sessões e tokens, rrweb, proxy de arquivos e watchdog

Como o Co-browse funciona por dentro: presença ao vivo, o ciclo da sessão e tokens de uso único, captura com rrweb, o proxy de arquivos e os watchdogs que encerram sessões travadas.

Jun 26, 2026

Veja este passo no vídeo · Privacidade e boas práticas

Este artigo é para administradores e equipes técnicas que querem entender como o Co-browse funciona internamente: as peças envolvidas quando um agente vê a tela do cliente ao vivo, como cada sessão é autorizada e o que impede uma sessão de ficar travada. Você não precisa disso para o uso do dia a dia (para isso, veja os artigos de início vinculados no fim), mas vai ajudar a diagnosticar problemas e a confiar no isolamento de dados.

Requisitos

  • O add-on Co-browse ativo no seu plano (validado pelo CobrowseGate).
  • O widget da Omnifox instalado no site do cliente.
  • Permissões de Caixa de entrada para o agente que inicia a sessão.

As peças e como se encaixam

  1. Presença ao vivo. Enquanto o cliente tem o widget carregado, a Omnifox sabe que ele está "presente" em uma página. Esse sinal é o que habilita o botão Co-browse no cabeçalho do chat (ChatHeader). Sem presença ativa, não há tela para solicitar.
  2. Solicitação de sessão. O agente clica em Co-browse e o evento cobrowse.session.requested é emitido pelo canal do widget. O widget carrega o bundle de captura de forma diferida (lazy-load) somente quando esse evento chega, para não pesar em sites que nunca o usam.
  3. Sessão + token. O backend cria uma sessão de Co-browse no banco do tenant, controla a concorrência com Redis e emite um token de cliente de uso único (1-shot). Esse token autentica o widget no canal privado private-cobrowse.{id} no Reverb; depois de usado, não serve mais.
  4. Captura com rrweb. O widget usa rrweb para gravar o DOM e as mudanças da página e os transmite como eventos eventWithTime. Do lado do agente, o modal CobrowseSession os reproduz com o Replayer do rrweb em modo liveMode.
  5. Ações do agente. Os cliques, a rolagem e a digitação do agente são traduzidos em referências xpath e enviados ao cliente, sem expor o bus do workspace (canal por sessão, não por workspace).
  6. Proxy de arquivos. Se a página do cliente carrega PDFs ou documentos privados do S3, a Omnifox os serve por /file-proxy (same-origin) para evitar problemas de CORS, assim como o /img-proxy faz com imagens.
  7. Watchdogs. Tarefas agendadas que rodam a cada minuto encerram sessões por timeout ou quando ficam stale (sem atividade), liberando a concorrência do Redis. Assim, uma aba fechada de repente nunca deixa a sessão "viva" para sempre.

Verificação

  • Inicie uma sessão de teste com a org [email protected] e confirme que você vê o DOM do cliente no modal.
  • Verifique que o canal em uso seja private-cobrowse.{id} (não um canal de workspace).
  • Feche a aba do cliente e confirme que, em menos de ~2 minutos, a sessão apareça como encerrada.

Se não funcionar

  • O botão Co-browse não aparece: confira se o add-on está ativo no plano (CobrowseGate) e se o cliente tem presença ao vivo.
  • O widget não conecta ao canal: geralmente é o token de uso único já consumido (refaça a solicitação) ou o Reverb fora do ar.
  • O widget mostra versão antiga após um deploy: o Cloudflare faz cache de /widget/*. Faça purge da zona omnifox.io depois de publicar cobrowse.js.
  • PDFs ou imagens não carregam: garanta que passem por /file-proxy e /img-proxy; um recurso direto do S3 vai falhar por CORS.

Dicas

  • O bundle do cliente vive separado (public/widget/cobrowse.js) e é compilado com sua própria config do Vite; não o misture com o build do app.
  • O Co-browse em produção é a fonte autoritativa: faça pull antes de editar arquivos de cobrowse e nunca sincronize dev→prod às cegas.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp