11 min de leitura

Solução de Problemas

Este guia abrange problemas comuns que você pode encontrar ao usar Zenovay e como resolvê-los.

Problemas com Script de Rastreamento

Script Não Carregando

Sintomas: Nenhum dado aparecendo no seu painel após instalar o script de rastreamento.

Possíveis Causas e Soluções:

1. Script Não Instalado Corretamente

Verifique se o script está na seção <head> de sua página:

<head>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
</head>

Verifique se:

A URL do script está correta
Seu data-tracking-code corresponde ao código mostrado nas configurações de script de rastreamento do seu domínio
O script carrega antes da tag de fechamento </head>

2. Content Security Policy (CSP) Bloqueando

Se você tiver um cabeçalho CSP, adicione Zenovay à sua lista de permissões:

Content-Security-Policy: script-src 'self' https://api.zenovay.com; connect-src 'self' https://api.zenovay.com;

3. Bloqueador de Anúncios ou Extensão de Privacidade

Algumas extensões do navegador podem bloquear scripts de análise. Para verificar:

Abra DevTools (F12)
Verifique a aba Console para solicitações bloqueadas
Teste em uma janela de incógnito sem extensões

Ao contrário da análise tradicional, Zenovay é amigável à privacidade e sem cookies, portanto é menos provável ser bloqueado por ferramentas de privacidade.

Script Carrega Mas Sem Dados

Sintomas: Script carrega com sucesso, mas o painel não mostra visitantes.

Soluções:

Verificar Console do Navegador

Abra o Console do DevTools e procure por erros:

// Você deve ver isto se estiver funcionando corretamente
[Zenovay] Tracking initialized for site: abc123
[Zenovay] Pageview tracked successfully

Verificar Solicitações de Rede

Abra DevTools → aba Network
Filtre por "zenovay" ou "api.zenovay.com"
Procure por solicitações POST para /e/YOUR_TRACKING_CODE
Verifique se as solicitações retornam 200 OK ou códigos de erro

Códigos de Erro Comuns:

Código de Status	Significado	Solução
401	ID do site inválido	Verifique seu `data-tracking-code`
403	Bloqueado por firewall	Verifique cabeçalhos CSP ou regras de firewall
429	Taxa limitada	Muitas solicitações, aguarde e tente novamente
500	Erro do servidor	Entre em contato com o suporte se persistente

Problemas de Posicionamento do Script

Zenovay detecta automaticamente erros comuns de instalação e mostra avisos no console do navegador. Você também verá diagnósticos no painel ao clicar em Verificar Instalação.

Onde colocar o script:

Sempre coloque o script Zenovay na seção <head> do seu HTML com o atributo defer:

Posicionamento corretoHTML

<head>
<!-- Outras tags head -->
<script defer data-id="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
</head>

Erros comuns:

Erro	Problema	Solução
Script em `<body>`	Pode perder o primeiro pageview, carrega muito tarde	Mover para `<head>`
Script ao final de `<body>`	Página totalmente carregada antes do rastreador executar	Mover para `<head>`
Falta de `defer`	Bloqueia a renderização da página	Adicionar atributo `defer`
Scripts duplicados	Aumenta pageviews e métricas	Remover tags de script extras
`data-id` incorreto	Eventos enviados para o site errado	Copie o snippet de Domains → seu site → General

Orientação específica por framework:

React: Use useEffect no seu componente App raiz, ou adicione a public/index.html <head>
Next.js (App Router): Use o componente <Script> em app/layout.tsx com strategy="afterInteractive"
Next.js (Pages Router): Adicione em pages/_document.tsx dentro de <Head>
Vue: Adicione a public/index.html seção <head>
WordPress: Use o plugin "Insert Headers and Footers" → Scripts in Header
Shopify: Adicione a theme.liquid antes de </head>

Problemas com proxy first-party:

Se você estiver usando um proxy first-party (ex: /api/_z/script.js):

Verifique se a URL do proxy retorna uma resposta 200 (não 404)
Verifique se o proxy encaminha o cabeçalho X-Zenovay-Real-IP
Tente carregar https://api.zenovay.com/z.js diretamente para isolar problemas de proxy vs. script
Certifique-se de que a Content-Security-Policy do seu servidor permite conexões com api.zenovay.com

Diagnósticos do console:

Quando há problemas de instalação, você verá mensagens como:

⚠️ [Zenovay] Installation issue: Script should be in <head> for accurate tracking. Currently in <body>.
   → Fix: Move the <script> tag into your website's <head> section.
   → Docs: https://docs.zenovay.com/guides/troubleshooting#script-placement

Esses avisos aparecem uma vez por sessão do navegador e são projetados para ajudá-lo a corrigir sua configuração.

Eventos Não Sendo Rastreados

Sintomas: Page views funcionam mas eventos customizados não aparecem.

Verificar Sintaxe do Evento:

// Correto
window.zenovay('track', 'button_click', {
  button_name: 'signup',
  page: '/pricing'
});

// Incorreto (falta nome do evento)
window.zenovay('track',{
  button_name: 'signup'
});

Verificar se Script Carregou:

// Verifique se Zenovay está disponível
if (window.zenovay) {
  console.log('Zenovay loaded');
  window.zenovay('track', 'custom_event');
} else {
  console.error('Zenovay not loaded yet');
}

Use Callback Ready:

window.addEventListener('zenovay:ready', function() {
  // Zenovay está pronto agora
  window.zenovay('track', 'page_load_complete');
});

Problemas com Painel

Dados Não Atualizando

Sintomas: O painel mostra dados antigos ou não atualiza em tempo real.

Soluções:

1. Limpar Cache do Navegador

Pressione Ctrl+Shift+R (Windows/Linux) ou Cmd+Shift+R (Mac) para atualização forçada.

2. Verificar Intervalo de Datas

Certifique-se de que o seletor de intervalo de datas mostra o período correto:

Clique no dropdown de intervalo de datas
Selecione "Hoje" ou "Últimas 24 horas"
Verifique se o fuso horário está correto em Settings → Account → Preferences

3. Aguardar Processamento

Dados em tempo real normalmente aparecem em 1-2 segundos, mas:

Métricas agregadas podem levar 5-10 minutos
Relatórios históricos atualizam a cada hora

Zero Visitantes Aparecendo

Sintomas: O painel mostra "0 visitantes" apesar do tráfego para seu site.

Passos de Diagnóstico:

Verificar ID do Site: Abra Domains → seu site → General e confirme se o código de rastreamento corresponde ao que está em seu script
Verificar Filtros: Remova quaisquer filtros ativos (localização, dispositivo, origem)
Testar Localmente: Visite seu site e verifique se você aparece na visualização em tempo real
Revisar Exclusões: Abra suas configurações de domínio e verifique a configuração de exclusões para ver se seu IP está excluído

Por padrão, Zenovay exclui localhost e 127.0.0.1 do rastreamento para evitar contar tráfego de desenvolvimento.

Números de Visitantes Incorretos

Sintomas: Contagens de visitantes não correspondem às expectativas ou outras ferramentas de análise.

Razões Comuns:

1. Diferenças de Definição

Zenovay conta:

Visitantes Únicos: Com base em ID de visitante anonimizado (janela de 24 horas)
Visitas: Sessões separadas (timeout de 30 minutos)
Pageviews: Cada carregamento de página

Outras ferramentas podem usar diferentes definições ou timeouts de sessão.

2. Impacto de Bloqueadores de Anúncios

Alguns visitantes usam bloqueadores de anúncios que podem:

Bloquear análise tradicional mas não Zenovay (amigável à privacidade)
Bloquear toda análise incluindo Zenovay (configurações agressivas)

3. Filtragem de Bots

Zenovay filtra automaticamente bots e crawlers conhecidos. Outras ferramentas podem:

Incluir tráfego de bot nas contagens
Usar diferentes métodos de detecção de bots

Problemas com Integração

Plugin WordPress Não Funcionando

Sintomas: A integração WordPress não rastreia visitantes.

Soluções:

1. Verificar Instalação do Plugin

Vá para Plugins → Installed Plugins
Certifique-se de que "Zenovay Analytics" está ativado
Verifique se a versão é a mais recente

2. Verificar Configuração de ID do Site

Vá para Settings → Zenovay
Verifique se o ID do Site está inserido corretamente
Salve as alterações e limpe o cache

3. Compatibilidade do Tema

Alguns temas podem conflitar com injeção de header/footer:

// Adicione ao functions.php do seu tema como fallback
function zenovay_tracking_script() {
  ?>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
  <?php
}
add_action('wp_head', 'zenovay_tracking_script');

4. Conflitos com Plugin de Cache

Se usar WP Super Cache, W3 Total Cache, ou similares:

Limpe todos os caches
Exclua script Zenovay de minificação/combinação
Teste em modo incógnito

React/SPA Não Rastreando Mudanças de Rota

Sintomas: Apenas o carregamento inicial da página é rastreado, mudanças de rota não são contadas.

Solução: Implemente rastreamento de roteamento no lado do cliente:

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Rastrear mudanças de rota
    if (window.zenovay) {
      window.zenovay('track', 'pageview', {
        path: location.pathname + location.search
      });
    }
  }, [location]);

  return <YourApp />;
}

Para Next.js App Router:

'use client';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function AnalyticsTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    if (window.zenovay) {
      window.zenovay('track', 'pageview');
    }
  }, [pathname, searchParams]);

  return null;
}

Problemas com API

Falhas de Autenticação

Sintomas: Solicitações de API retornam 401 Unauthorized.

Verificar Chave de API:

# Teste sua chave de API
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Erros Comuns:

Usando ID do site em vez de chave de API
Faltando cabeçalho X-API-Key
Chave de API expirada ou revogada
Chave de API errada para ambiente (teste vs produção)

Gerar Nova Chave de API:

Vá para Settings → Security → API keys
Clique em "Create New Key"
Copie a chave imediatamente (mostrada apenas uma vez)
Substitua a chave antiga em sua aplicação

Taxa Limitada

Sintomas: API retorna 429 Too Many Requests.

Verificar Cabeçalhos de Limite de Taxa:

curl -I -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Procure por:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1673456789

O valor de X-RateLimit-Limit reflete o limite por minuto do seu plano (ex: 10 para Free, 30 para Pro, 60 para Scale, 120 para Enterprise).

Soluções:

Implemente backoff exponencial (veja Rate Limits)
Faça cache de respostas de API onde possível
Agrupe solicitações em vez de chamadas individuais
Considere fazer upgrade do seu plano para limites maiores

Problemas de Desempenho

Script Desacelerando Carregamento da Página

Sintomas: Tempos de carregamento da página aumentaram após adicionar Zenovay.

Verificar Carregamento Assíncrono:

Certifique-se de que o script tem o atributo async:

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Teste de Impacto:

Use DevTools do navegador ou Lighthouse:

Execute auditoria Lighthouse com e sem script
Compare métricas "Time to Interactive"
Verifique "Blocking Time"

O script Zenovay é tipicamente < 5KB gzipped e carrega assincronamente, adicionando < 50ms ao carregamento da página.

Painel Carregando Lentamente

Sintomas: O painel leva muito tempo para carregar gráficos e dados.

Soluções:

1. Reduzir Intervalo de Datas

Carregar 12 meses de dados é mais lento que 7 dias:

Use intervalos de datas menores quando possível
Aplique filtros para reduzir volume de dados

2. Limpar Dados do Navegador

Limpe cache do navegador e cookies
Desabilite extensões do navegador que podem interferir
Tente um navegador diferente

3. Verificar Rede

Teste sua velocidade de conexão de internet
Tente em uma rede diferente
Verifique se o firewall corporativo está limitando

Problemas de Precisão de Dados

Dados Geográficos Faltando

Sintomas: Alguns visitantes mostram localização "Desconhecida".

Causas:

Uso de VPN ou proxy pelo visitante
Navegadores focados em privacidade que mascaram localização
Redes corporativas com endereços IP centralizados

Este é um comportamento esperado e afeta 5-15% dos visitantes dependendo do seu público.

Referência Mostra como "Direto"

Sintomas: A maioria do tráfego mostra como "Direct" em vez da fonte real.

Causas Comuns:

1. Transições HTTPS → HTTP

Referência é removida ao ir de HTTPS para HTTP. Solução: Use HTTPS em seu site.

2. Política de Referência

Alguns sites usam políticas de referência rígidas:

<meta name="referrer" content="no-referrer">

Esta é a política do site de envio, não algo que você pode controlar.

3. Aplicativos Móveis e Email

Tráfego de aplicativos móveis e clientes de email frequentemente mostra como direto - isto é normal e esperado.

Obtendo Ajuda

Se você ainda estiver experimentando problemas após tentar estas soluções:

Verificar Status do Serviço

Visite status.zenovay.com para ver se há uma interrupção ou incidente conhecido.

Coletar Informações de Diagnóstico

Antes de contatar o suporte, reúna:

Logs do Console do Navegador:
- Abra DevTools → Console
- Copie quaisquer mensagens de erro
- Tire screenshot
Solicitações de Rede:
- Abra DevTools → Network
- Filtre por "zenovay"
- Screenshot de solicitações falhadas com códigos de status
Informações do Site:
- URL do seu site
- ID do Site do painel
- Plataforma/CMS (WordPress, customizado, etc.)
- Volume de tráfego aproximado

Contatar Suporte

Email: [email protected]

Incluir:

Descrição detalhada do problema
Passos que você já tentou
Informações de diagnóstico acima
Screenshots ou gravações de tela

Tempos de Resposta:

Plano Free: 48-72 horas
Planos Pagos: 24 horas
Enterprise: 4 horas (SLA)

Ajuda da Comunidade

GitHub: github.com/zenovay
Documentação: Procure em nossos docs por tópicos específicos
Assistente AI: Use o widget de chat em qualquer página de docs

Solução de Problemas

Problemas com Script de Rastreamento

Script Não Carregando

Script Carrega Mas Sem Dados

Problemas de Posicionamento do Script

Eventos Não Sendo Rastreados

Problemas com Painel

Dados Não Atualizando

Zero Visitantes Aparecendo

Números de Visitantes Incorretos

Problemas com Integração

Plugin WordPress Não Funcionando

React/SPA Não Rastreando Mudanças de Rota

Problemas com API

Falhas de Autenticação

Taxa Limitada

Problemas de Desempenho

Script Desacelerando Carregamento da Página

Painel Carregando Lentamente

Problemas de Precisão de Dados

Dados Geográficos Faltando

Referência Mostra como "Direto"

Obtendo Ajuda

Verificar Status do Serviço

Coletar Informações de Diagnóstico

Contatar Suporte

Ajuda da Comunidade

Recursos Adicionais