Analytics no Astro

Instalação

1. 1Instale o SDK

   No Astro, variáveis disponíveis no navegador começam com PUBLIC_.

   npm install @racoelho/analytics

   PUBLIC_ANALISA_SITE_KEY=YOUR_SITE_KEY

2. 2Crie a instância num módulo

   Scripts do Astro são empacotados e rodam uma vez por carregamento, mesmo que o módulo seja importado em vários componentes.

   import { Analytics } from '@racoelho/analytics'
   
   // módulo importado por vários scripts: o Astro empacota uma vez, a instância é única
   export const analytics = new Analytics({
     siteKey: import.meta.env.PUBLIC_ANALISA_SITE_KEY,
   })

3. 3Importe no layout

   Use o mesmo layout em todas as páginas. A primeira pageview sai quando o módulo é carregado.

   ---
   const { title } = Astro.props
   ---
   <html lang="pt-BR">
     <head>
       <meta charset="utf-8" />
       <title>{title}</title>
     </head>
     <body>
       <slot />
       <script>
         import { analytics } from '../lib/analytics'
   
         // com <ClientRouter /> (view transitions): conta cada navegação
         document.addEventListener('astro:page-load', () => analytics.pageview())
       </script>
     </body>
   </html>

Eventos e metas

Em qualquer componente .astro, um <script> importa a mesma instância e chama track(nome, propriedades).

<button id="signup">Criar conta</button>

<script>
  import { analytics } from '../lib/analytics'

  // delegação no document: continua valendo depois de view transitions
  document.addEventListener('click', (event) => {
    if (event.target instanceof Element && event.target.closest('#signup')) {
      analytics.track('signup_click', { place: 'hero' })
    }
  })
</script>

Crie no painel uma meta do tipo evento com o nome signup_click. Para páginas de obrigado, uma meta do tipo caminho basta.

Navegação entre páginas

Sem view transitions, cada página é um carregamento completo e é contada sozinha. Com <ClientRouter />, o Astro troca de página sem recarregar e o SDK não percebe — o ouvinte de astro:page-load no layout cobre isso (na primeira carga ele repete a pageview, e o SDK descarta a duplicata).

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.
4. Se usar view transitions, navegue entre duas páginas e confira um novo page_view.

Problemas comuns

Com view transitions, os cliques param de contar depois de navegar

Scripts empacotados rodam uma vez só; o ouvinte preso num botão some quando o Astro troca o conteúdo da página. Registre o ouvinte no document e filtre pelo alvo, como no exemplo.

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.