Analytics no Nuxt

Instalação

1. 1Instale o SDK e configure a chave

   O Nuxt preenche runtimeConfig.public com variáveis de ambiente NUXT_PUBLIC_*.

   npm install @racoelho/analytics

   export default defineNuxtConfig({
     runtimeConfig: {
       public: {
         analisaSiteKey: '',
       },
     },
   })

   NUXT_PUBLIC_ANALISA_SITE_KEY=YOUR_SITE_KEY

2. 2Crie o plugin

   O sufixo .client no nome do arquivo faz o Nuxt carregar o plugin só no navegador — o SDK não roda no servidor.

   import { Analytics } from '@racoelho/analytics'
   
   export default defineNuxtPlugin(() => {
     const config = useRuntimeConfig()
     // o sufixo .client garante que isto só roda no navegador
     const analytics = new Analytics({ siteKey: config.public.analisaSiteKey })
   
     useRouter().afterEach((to, from) => {
       // só quando o caminho muda; a primeira carga já foi contada
       if (to.path !== from.path) analytics.pageview()
     })
   
     return { provide: { analytics } }
   })

Eventos e metas

Em qualquer componente, pegue $analytics do useNuxtApp() e chame track(nome, propriedades).

<script setup lang="ts">
const { $analytics } = useNuxtApp()

function subscribe() {
  $analytics.track('newsletter_signup', { place: 'footer' })
}
</script>

<template>
  <button @click="subscribe">Assinar a newsletter</button>
</template>

Crie uma meta do tipo evento newsletter_signup no painel. Como o plugin é só do cliente, use $analytics em handlers de evento ou em onMounted, nunca durante a renderização no servidor.

Navegação entre páginas

Depois da primeira carga o Nuxt navega sem recarregar, e o SDK não percebe isso sozinho — o afterEach do plugin conta cada nova página. Mudanças só de query string não contam como página nova.

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. Navegue por um <NuxtLink> e confira um novo page_view no POST seguinte.

Problemas comuns

$analytics é undefined no componente

O código rodou no servidor, onde o plugin .client não existe. Mova a chamada para um handler de clique ou para onMounted.

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.