Analytics num site HTML

Instalação

1. 1Cole o snippet antes do </body>

   Em todas as páginas — se o site tem um template ou include de rodapé, coloque lá. Troque YOUR_SITE_KEY pela sua chave.

   <script src="https://cdn.jsdelivr.net/npm/@racoelho/analytics@0.2/dist/index.global.js"></script>
   <script>window.analytics = new Analytics.Analytics({ siteKey: 'YOUR_SITE_KEY' })</script>

   A primeira linha baixa o SDK (uns 4KB comprimido); a segunda cria a instância em window.analytics. A pageview, os Web Vitals e os erros de JavaScript passam a ser enviados sozinhos.

2. 2Confira o lugar certo

   Uma página completa fica assim. A ordem importa: o segundo <script> usa o que o primeiro carregou, então não ponha async nem defer no primeiro.

   <!doctype html>
   <html lang="pt-BR">
     <head>
       <meta charset="utf-8" />
       <title>Meu site</title>
     </head>
     <body>
       <!-- conteúdo da página -->
   
       <script src="https://cdn.jsdelivr.net/npm/@racoelho/analytics@0.2/dist/index.global.js"></script>
       <script>window.analytics = new Analytics.Analytics({ siteKey: 'YOUR_SITE_KEY' })</script>
     </body>
   </html>

3. 3Publique

   Suba os arquivos e abra o site. Não há mais nada para configurar.

Eventos e metas

Use window.analytics.track(nome, propriedades) para qualquer ação. Há atalhos prontos para casos comuns, como formSubmit, signup e purchase.

<button id="cta">Começar</button>

<form id="newsletter">…</form>

<script>
  // clique num botão
  document.getElementById('cta').addEventListener('click', function () {
    window.analytics.track('cta_click', { place: 'hero' })
  })

  // envio de formulário (helper pronto do SDK)
  document.getElementById('newsletter').addEventListener('submit', function () {
    window.analytics.formSubmit('newsletter', 'Newsletter')
  })
</script>

No painel, crie uma meta do tipo evento com o mesmo nome (cta_click) para ver a conversão por origem, UTM e país. Para páginas de agradecimento, use uma meta do tipo caminho (ex.: /obrigado) — sem código.

Navegação entre páginas

Num site de várias páginas, cada página carrega o script de novo e conta a própria pageview: não há nada a fazer. Se você troca a URL sem recarregar (com history.pushState), chame pageview() depois da troca. Rotas com # não são diferenciadas: o SDK registra o caminho sem o fragmento.

// seu código troca a URL sem recarregar…
history.pushState({}, '', '/pricing')
// …e avisa o SDK depois
window.analytics.pageview()

Confira se está funcionando

1. Abra o site publicado numa janela comum, sem bloqueador de anúncios.
2. Nas ferramentas do navegador, aba Network, filtre por v1/i: deve aparecer um POST com status 200 em até 3 segundos (ou quando você sai da página).
3. No painel, os eventos aparecem em cerca de 30 segundos.

Problemas comuns

Erro Analytics is not defined no console

O segundo script rodou antes do primeiro terminar. Tire async/defer da tag do SDK ou mantenha as duas linhas juntas, nessa ordem.

A requisição volta 403 (origin_not_allowed)

O domínio não está em Allowed origins nas configurações do site. Cadastre a origem exata — com https://, com e sem www, e endereços de teste como http://localhost:3000 se quiser medir em desenvolvimento.

Nenhuma requisição aparece na aba Network

O SDK respeita o Do Not Track por padrão: se o seu navegador envia DNT, nada é enviado. Teste em outro navegador ou perfil. Bloqueadores de anúncio também podem barrar o script.

As pageviews aparecem em dobro

O SDK foi inicializado duas vezes (por exemplo, o script colado no tema e também por um plugin). Mantenha uma única instância por página.