6 min de leitura

Extensão de navegador

O Zenovay Analytics Inspector é uma WebExtension para Chrome + Firefox que detecta o script de tracking do Zenovay em qualquer página e mostra eventos ao vivo em um popup. É uma ferramenta de diagnóstico — uma alternativa mais rápida, dentro do navegador, a abrir o DevTools ou o fluxo de verificação de instalação do dashboard.

Zero telemetria. A extensão nunca faz chamadas de rede para o Zenovay. Todo o estado fica em chrome.storage.session e é apagado quando você fecha o navegador.

Instalação

Chrome Web Store

Em breve — pacote de submissão preparado. Vamos linkar aqui assim que for aprovado.

Firefox Add-ons (AMO)

Em breve — pacote de submissão preparado.

A partir do código (para desenvolvedores)

git clone https://github.com/zenovay/extension-zenovay.git
cd extension-zenovay
npm install
npm run build

Depois, no Chrome abra chrome://extensions, ative o modo desenvolvedor (chave no canto superior direito), clique em Carregar sem compactação e escolha o diretório dist/.

No Firefox, abra about:debugging#/runtime/this-firefox, clique em Carregar extensão temporária e escolha dist/manifest.json.

Como ler o badge

Badge	Significado
(vazio)	Nenhum script de tracking do Zenovay detectado nesta página
Âmbar `!`	Script detectado, mas nenhum evento disparado ainda
Verde `ON`	Script detectado e disparando eventos
Azul `C`	Script detectado, rodando em modo sem cookies

O estado do badge é por aba, então uma única sessão de navegador pode mostrar estados diferentes para sites diferentes simultaneamente.

Quando você clica no badge, o popup reporta:

Cartão de status — estado de detecção atual com um indicador pulsante enquanto há eventos ao vivo
Código de tracking — o ID do projeto (ex.: ZV_abc123…)
Origem do script — a URL de onde o tracker é carregado
Cookieless — se data-cookieless="true" está na tag script OU cookielessMode: true em ZENOVAY_TRACKER_CONFIG
GPC — se o usuário tem o Global Privacy Control ativado nas configurações do navegador
Endpoint da API — para onde o tracker envia eventos
Eventos ao vivo — lista rolável dos últimos 50 eventos (tipo + tempo relativo)
Abrir no dashboard do Zenovay — deep-link para o dashboard correspondente

Eventos ao vivo: Caminho A vs Caminho B

O tracker do Zenovay só emite o evento customizado zenovay:debug:event quando o site define data-debug="true". Sites em produção tipicamente não fazem isso.

Caminho B (padrão). A extensão escuta zenovay:debug:event e drena window._zenovayDebugBus. Em uma página de debug (ou em app.zenovay.com), você verá eventos chegando. Em um site de produção sem modo debug, o popup mostra:

Ative data-debug="true" na tag script para ver eventos ao vivo, ou ative a inspeção profunda abaixo.

Caminho A (opt-in). Ative Beta: inspeção profunda no popup. A extensão patcha navigator.sendBeacon e window.fetch para interceptar os POSTs de eventos para a API do tracker. Funciona em qualquer site, com duas ressalvas:

A extensão pode conflitar com outras extensões que também patchem chamadas de rede.
Eventos disparados antes de você ativar o toggle não são capturados. Se 3 segundos passarem sem eventos, o popup oferece um Recarregar de um clique para capturar a pageview inicial.

Marcamos o Caminho A como Beta até termos coletado feedback sobre colisões. Desative se notar comportamento estranho em algum site.

Sinais de detecção

A extensão investiga cinco fontes, em ordem, todas dentro do MAIN world da página:

Varredura de tags script — script[src*="/z.js"], script[src*="zenovay-tracker"], script[data-id], script[data-tracking-code], script[data-website-id].
Sonda global — typeof window.zenovay === 'function', consultado por até 5 segundos em intervalos de 200 ms.
Sonda de configuração — lê window.ZENOVAY_TRACKER_CONFIG se o tracker foi carregado via endpoint /load (com config injetada pelo dashboard).
Subscrição de eventos — escuta zenovay:debug:event em window.
Drenagem de buffer — captura um snapshot de window._zenovayDebugBus se presente.

Qualquer sinal sozinho já basta para marcar uma página como "detectada".

Permissões

Permissão	Para quê
`activeTab`	Ler o DOM da aba ativa quando você abre o popup
`storage`	Cachear os últimos 50 eventos por aba em session storage
`scripting`	Injetar a sonda de detecção no MAIN world da página
`host_permissions: <all_urls>`	Detectar o Zenovay em qualquer site que você visite

Explicitamente não solicitadas: tabs, webRequest, cookies, history, bookmarks, downloads. A extensão não consegue ler suas outras abas, seu histórico ou suas senhas salvas.

Privacidade

O Inspector é construído para honrar a postura cookieless mais ampla do Zenovay:

Sem chamadas de rede — a extensão nunca envia dados para api.zenovay.com nem para qualquer outro lugar.
Sem cookies — nem a extensão nem sua UI escrevem cookies. O estado do toggle fica em chrome.storage.local (poucos bytes para a preferência Beta: inspeção profunda). Dados de eventos por aba ficam em chrome.storage.session, limpo ao fechar o navegador.
Sem armazenamento persistente de payloads — os patches do Caminho A parseiam os corpos de eventos apenas em memória.
O deep-link é iniciado pelo usuário — clicar em Abrir no dashboard do Zenovay é a única ação de saída e requer um clique deliberado.

Resolução de problemas

O badge fica vazio em um site que tenho certeza tem Zenovay

Recarregue a aba com força (Cmd/Ctrl + Shift + R). A sonda injetada roda em document_idle; uma carga limpa dá a ela uma chance limpa.
Inspecione o código-fonte da página por padrões script src casando com /z.js, zenovay-tracker, ou data-id="…". Se nenhum estiver presente, o script de fato não está carregado.
Verifique a CSP do site — uma diretiva script-src estrita pode estar bloqueando o tracker por inteiro.

O badge mostra âmbar `!` mas estou esperando eventos

Esse é o Caminho B funcionando como projetado. O script está carregado mas não emite zenovay:debug:event porque o site não tem data-debug="true". Ative Beta: inspeção profunda no popup, depois recarregue.

A lista de eventos fica vazia depois de ativar a inspeção profunda

Se um banner de dica aparecer em 3 segundos — clique em Recarregar. A pageview inicial do tracker dispara uma vez por carregamento de página; o Caminho A só captura eventos a partir do momento em que foi ativado.

O indicador cookieless mostra ✗ mas configurei cookieless

data-cookieless="true" precisa estar na própria tag <script>, como string "true". Confirme:

<script src="https://api.zenovay.com/z.js" data-id="SEU_CÓDIGO" data-cookieless="true"></script>

Não data-cookieless (só presença) nem data-cookieless="1". O tracker lê com correspondência estrita de string.

Código aberto

A extensão é licenciada MIT e desenvolvida abertamente em github.com/zenovay/extension-zenovay. Issues e pull requests bem-vindos.