9 min de leitura

Overlay de Depuração

Um overlay flutuante, na própria página, que transmite todo evento que o seu rastreador Zenovay está enviando — tipo, props, modo sem cookies, estado de GPC, estado de consentimento e versão do script — sem você precisar abrir o devtools do navegador. PII é mascarado. O overlay é duplamente protegido: ele nunca é ativado a menos que você tenha optado por habilitá-lo na página de configurações do site e anexado ?zenovay_debug=1 a uma URL no seu site.

As duas proteções são obrigatórias. Habilitar a configuração do site sozinha não faz nada. Adicionar ?zenovay_debug=1 sozinho não faz nada. As duas precisam estar verdadeiras no mesmo carregamento de página. Isso evita exposição acidental a visitantes comuns.

Por que usar

Ao verificar uma instalação — desenvolvimento local, staging ou um teste rápido em produção — você normalmente quer um único fato: "o rastreador está disparando os eventos certos com as props certas?" A resposta tradicional é: abrir o devtools → aba Rede → filtrar por /e/ ou /api/_z → clicar em cada requisição → ler o corpo JSON. O overlay de depuração reduz tudo isso a uma olhada: cada evento que o rastreador envia aparece como uma linha, clique em qualquer linha para ver o JSON completo, clique em "Copy JSON" para colá-lo em um chamado de suporte.

Também é útil para integrar novos colegas ("é exatamente isto que enviamos") e para documentar comportamento intencional (faça uma captura de tela do overlay durante um fluxo de usuário sabidamente correto e guarde como linha de base de regressão).

Como habilitar

Entre em app.zenovay.com e abra a página Domínios.
Clique no domínio que você quer depurar.
Abra Configurações → Avançado e role até a seção Configurações básicas.
Ative Allow Debug Overlay.
No seu próprio site, navegue até qualquer URL com ?zenovay_debug=1 anexado — por exemplo https://seu-site.com/?zenovay_debug=1 ou https://seu-site.com/checkout?zenovay_debug=1.

O overlay aparece no canto inferior direito cerca de um segundo depois que o rastreador é carregado.

Propagação do cache: a configuração do rastreador fica em cache na borda por até 5 minutos depois que você aciona o interruptor. Se o overlay não aparecer imediatamente, recarregue a página com cache zerado (Cmd/Ctrl + Shift + R) ou aguarde alguns minutos.

O que você verá

O overlay tem três regiões:

Chips do cabeçalho mostram o estado em tempo de execução do rastreador na página atual:

cookieless ON | OFF — se o modo sem cookies está ativo para este site. ON significa que o rastreador está usando IDs em memória com escopo de janela e gravando zero cookies. OFF significa que IDs de sessão/visitante baseados em cookies estão em uso.
GPC ON | OFF — se o navegador do visitante enviou um sinal de Global Privacy Control (Sec-GPC: 1 / navigator.globalPrivacyControl === true). Quando ON, o enriquecimento comportamental (B2B, scoring) é pulado no servidor.
consent: <state> — o último estado de consentimento que o rastreador observou (opt-in, opt-out, unknown). Se você usa uma plataforma de gestão de consentimento, isso reflete a escolha do visitante.
v<version> — a versão do script do rastreador rodando no momento na página.

Lista de eventos mostra os 20 eventos enviados mais recentes, do mais novo para o mais antigo. Cada linha mostra:

Carimbo de tempo do relógio (HH:MM:SS, hora local do navegador)
Tipo do evento
Até 4 chaves de propriedade abreviadas

Clique em qualquer linha para abrir o modal de JSON.

Modal de JSON mostra o JSON completo do evento (depois do mascaramento de PII). Use o botão Copy JSON para copiá-lo para a área de transferência — útil para compartilhar com um colega ou anexar a um chamado de suporte.

Lendo os tipos de evento

Tipo de evento	O que significa
`pageview`	Uma nova página foi visualizada. Inclui URL, referrer, parâmetros UTM, classe de dispositivo, tamanho da tela.
`heartbeat`	O visitante ainda está na página. Dispara a cada ~2 segundos enquanto inativo, para podermos calcular tempo na página com precisão.
`page_exit`	O visitante fechou a aba ou navegou para outro lugar. Delta final de tempo na página.
`outbound_link`	Um clique em uma tag `<a>` cujo `href` aponta para fora do seu domínio.
`goal_completion`	Um objetivo configurado disparou. Inclui o nome do objetivo e quaisquer parâmetros personalizados.
`funnel_step`	O visitante avançou para uma etapa de um funil configurado.
`custom_event`	Uma chamada `zenovay.track('event_name', {...})` do seu próprio código.
`error`	Um erro JavaScript capturado pelo rastreador (só é enviado se o rastreamento de erros estiver habilitado no seu plano).
`core_web_vitals`	Medições LCP / CLS / INP da página atual (enviadas uma vez por página, depois que as métricas se estabilizam).
`session_replay`	Um trecho de dados de session replay foi enviado. O overlay mostra apenas que o trecho foi enviado — nunca o conteúdo da gravação.
`frustration_signal`	Foi detectado um sinal de rage-click, dead-click ou jitter excessivo de rolagem.

Mascaramento de PII

O overlay aplica uma máscara no lado da exibição a todo evento antes de mostrá-lo na tela. A máscara cobre dois casos:

Correspondência por nome do campo (chave) — qualquer prop com um destes nomes de chave é substituída por [MASKED]:

email, phone, first_name, last_name, name, customer_id, user_id, ip, ip_address, client_ip, user_agent, useragent, ua

Correspondência por padrão no valor — aplicada mesmo que o nome da chave não bata:

Strings que correspondem ao formato de email ([email protected]) são parcialmente censuradas (a***@b***.tld).
Strings que correspondem a IPv4 (1.2.3.4) são substituídas por [IP].
Strings com mais de 80 caracteres que contêm Mozilla|WebKit|Chrome|Safari|Firefox são truncadas e marcadas como [UA truncated].

O mascaramento acontece apenas na camada de exibição do overlay. O payload bruto do evento que o rastreador realmente envia ao Zenovay não é alterado — é ele que alimenta seus dashboards. A máscara afeta apenas o que você vê na tela, então capturas de tela e cópias do JSON do overlay podem ser compartilhadas com segurança.

Privacidade e conformidade

O overlay foi projetado para ser seguro de habilitar em qualquer ambiente, mas você ainda deve entender exatamente o que ele faz e o que não faz:

Zero cookies, zero localStorage. O barramento de eventos é um array JavaScript comum em window (window._zenovayDebugBus). Ele desaparece quando a aba é fechada.
Sem registro remoto. O overlay nunca faz uma chamada de rede. Tudo o que você vê é renderizado a partir de dados já presentes na memória do navegador.
Carregamento sob demanda. A UI do overlay é um recurso HTTP separado (/debug-overlay.js) que só é baixado quando as duas proteções estão satisfeitas. Visitantes sem o parâmetro de URL baixam zero bytes do overlay.
A invariante do rastreador sem cookies é preservada. Se o seu site está no modo sem cookies, habilitar o overlay não muda o comportamento do rastreador — nenhum cookie é gravado, os mesmos IDs temporários com escopo de janela são usados, e o chip cookieless no cabeçalho mostra ON.
GPC é honrado de qualquer forma. O overlay lê o estado de GPC da configuração do rastreador, mas não o ignora.

Solução de problemas

"Adicionei ?zenovay_debug=1 e nada acontece."

Confira novamente se a configuração do site está ligada. As duas proteções precisam estar verdadeiras.
Recarregue a página com cache zerado (Cmd/Ctrl + Shift + R) — a configuração do rastreador fica em cache por até 5 minutos depois que você aciona o interruptor.
Confirme que sua versão do rastreador suporta o overlay abrindo o devtools e executando window.ZENOVAY_TRACKER_CONFIG — se allowDebugOverlay for false mesmo com o interruptor ligado, o cache ainda não foi invalidado.
Verifique se nenhuma Content-Security-Policy no seu site está bloqueando scripts de api.zenovay.com.

"O overlay aparece, mas nenhum evento surge."

Provoque uma interação na página (clique em um link, role, navegue) para fazer o rastreador disparar algo.
Se mesmo assim você não vir nada, talvez o rastreador não esteja enviando — cruze com o Status da instalação, que sonda o mesmo caminho a partir do servidor.

"O overlay some quando troco de rota numa SPA."

O overlay deveria ser remontado automaticamente em mudanças de rota. Se não for, é um caso de borda conhecido com frameworks que removem agressivamente filhos de document.body — por favor, reporte um caso reproduzível em help.zenovay.com.

"Tenho vários rastreadores Zenovay na minha página."

Apenas um overlay é montado. O primeiro rastreador a inicializar vence (proteção via window._zenovayDebugOverlayMounted).

"Vejo [MASKED] em campos que enviei de propósito."

Isso é esperado. A máscara é aplicada incondicionalmente a uma lista de nomes de chaves comuns de PII. Se você precisa exibir um campo não-PII com um nome que parece sensível (por exemplo, você usou name para um rótulo não pessoal), renomeie a prop e teste de novo.

"O overlay cobre uma parte importante da minha UI."

Clique no × no cabeçalho para esconder o overlay até o próximo carregamento de página.

Quando desabilitar

Recomendamos desligar o interruptor Allow debug overlay em produção depois que você verificou a sua instalação. Embora a dupla proteção evite exposição acidental a visitantes comuns (que nunca anexaram ?zenovay_debug=1), manter a flag do site desligada por padrão remove o segundo fator inteiramente e torna a exposição acidental impossível — mesmo que um desenvolvedor compartilhe por engano uma URL de depuração.

Compatibilidade com navegadores

O overlay funciona em todos os navegadores evergreen (Chrome, Firefox, Safari, Edge) e falha graciosamente em navegadores antigos sem URLSearchParams ou com CSP restritiva — ele nunca lança um erro não tratado na página hospedeira.

Relacionados

Status da instalação — sonda do lado do servidor para a atividade recente do seu rastreador.
Script de rastreamento — referência completa do snippet do rastreador, incluindo todos os atributos data-*.
Conformidade de privacidade — modo sem cookies, tratamento de GPC, registro de consentimento.