7 min de leitura

Adicionar o Zenovay Analytics ao Nuxt

O Zenovay Analytics combina perfeitamente com o Nuxt, oferecendo aos desenvolvedores Vue uma forma rápida e que respeita a privacidade para rastrear visitantes em aplicações Nuxt com renderização no servidor, geração estática e híbridas. A integração leva cerca de dois minutos: adicione o script de rastreamento via nuxt.config.ts ou como um plugin do lado do cliente, e o Zenovay começa imediatamente a registrar visualizações de página, referenciadores, dados do navegador e insights geográficos em tempo real. O rastreador pesa menos de 1 KB, carrega de forma assíncrona para proteger seus Core Web Vitals e detecta automaticamente as mudanças de rota do lado do cliente via Vue Router. Este guia cobre tanto a abordagem baseada em configuração quanto a de plugin, além de rastreamento de eventos personalizados com composables, identificação de usuários, modo sem cookies compatível com GDPR e considerações sobre renderização no servidor específicas do Nuxt 3.

Configuração rápida (2 minutos)

Existem duas formas de adicionar o Zenovay ao Nuxt. Escolha a que melhor se adapta ao seu projeto.

Passo 1: Obtenha seu código de rastreamento

Acesse o painel do Zenovay e copie seu código de rastreamento em Settings → Tracking Code.

Opção A: nuxt.config.ts (Recomendado)

A abordagem mais simples. Adicione o script ao app.head na configuração do Nuxt:

nuxt.config.tsTypeScript

export default defineNuxtConfig({
app: {
  head: {
    script: [
      {
        defer: true,
        'data-tracking-code': 'YOUR_TRACKING_CODE',
        src: 'https://api.zenovay.com/z.js',
      },
    ],
  },
},
})

Pronto! O Zenovay rastreará automaticamente as visualizações de página em todas as suas rotas Nuxt, incluindo as navegações do lado do cliente.

Opção B: Plugin do lado do cliente

Se preferir mais controle, crie um plugin Nuxt que carregue o script no cliente:

plugins/zenovay.client.tsTypeScript

export default defineNuxtPlugin(() => {
if (typeof document === 'undefined') return;

const script = document.createElement('script');
script.defer = true;
script.dataset.trackingCode = 'YOUR_TRACKING_CODE';
script.src = 'https://api.zenovay.com/z.js';
document.head.appendChild(script);
})

O sufixo .client.ts garante que este plugin execute apenas no navegador, nunca durante o SSR.

Passo 2: Verifique sua instalação

Inicie o servidor de desenvolvimento com npx nuxi dev, visite uma página e verifique o painel do Zenovay. Você deverá ver um visitante em tempo real em segundos.

Rastreamento de navegação SPA

O Nuxt usa o Vue Router para roteamento do lado do cliente. O Zenovay detecta automaticamente as mudanças de rota via History API (pushState / popstate), de modo que cada navegação registra uma nova visualização de página sem nenhuma configuração adicional.

Funciona com:

Componentes <NuxtLink>
Navegação programática com navigateTo()
Chamadas a useRouter().push()
Botões de voltar/avançar do navegador

Eventos personalizados com composables

Crie um composable reutilizável para chamadas de analytics organizadas em todo o seu app:

composables/useZenovay.tsTypeScript

export function useZenovay() {
function track(event: string, data?: Record<string, any>) {
  if (import.meta.client && window.zenovay) {
    window.zenovay('track', event, data);
  }
}

function identify(userId: string, traits?: Record<string, any>) {
  if (import.meta.client && window.zenovay) {
    window.zenovay('identify', userId, traits);
  }
}

function trackGoal(goalName: string, data?: Record<string, any>) {
  if (import.meta.client && window.zenovay) {
    window.zenovay('goal', goalName, data);
  }
}

function trackRevenue(amount: number, currency = 'USD') {
  if (import.meta.client && window.zenovay) {
    window.zenovay('revenue', amount, currency);
  }
}

return { track, identify, trackGoal, trackRevenue };
}

O Nuxt importa automaticamente os composables do diretório composables/, então você pode usá-los em qualquer lugar sem uma instrução de importação:

pages/pricing.vueVUE

<script setup lang="ts">
const { track } = useZenovay();

function handleUpgrade(plan: string) {
track('upgrade_clicked', { plan, location: 'pricing_page' });
navigateTo('/checkout?plan=' + plan);
}
</script>

<template>
<div>
  <h1>Pricing</h1>
  <button @click="handleUpgrade('pro')">Upgrade to Pro</button>
  <button @click="handleUpgrade('scale')">Upgrade to Scale</button>
</div>
</template>

Rastrear eventos em componentes

components/ContactForm.vueVUE

<script setup lang="ts">
const { track } = useZenovay();

const form = reactive({ name: '', email: '', message: '' });

async function handleSubmit() {
track('form_submitted', {
  form: 'contact',
  has_message: form.message.length > 0,
});

await $fetch('/api/contact', { method: 'POST', body: form });
}
</script>

<template>
<form @submit.prevent="handleSubmit">
  <input v-model="form.name" placeholder="Name" required />
  <input v-model="form.email" type="email" placeholder="Email" required />
  <textarea v-model="form.message" placeholder="Message"></textarea>
  <button type="submit">Send</button>
</form>
</template>

Considerações sobre renderização no servidor

O Nuxt 3 renderiza páginas no servidor por padrão. O script do Zenovay é executado inteiramente no cliente, portanto, mantenha estas regras em mente:

Nunca chame window.zenovay em middlewares de servidor, rotas de API ou arquivos em server/
Sempre proteja as chamadas do lado do cliente com import.meta.client ou process.client
O script head do nuxt.config.ts é seguro porque o navegador gerencia o carregamento do script
Use o sufixo .client.ts para plugins que precisam do objeto window

Segurança SSRTypeScript

// ✅ Seguro: protegido com import.meta.client
if (import.meta.client && window.zenovay) {
window.zenovay('track', 'page_view');
}

// ✅ Seguro: dentro de onMounted (hook de ciclo de vida exclusivo do cliente)
onMounted(() => {
if (window.zenovay) {
  window.zenovay('track', 'component_visible');
}
});

// ❌ Inseguro: executado durante o SSR — causará erro!
// window.zenovay('track', 'page_view');

Rastreamento com middleware de rota

Rastreie transições de rota específicas com o middleware de rota do Nuxt:

middleware/analytics.global.tsTypeScript

export default defineNuxtRouteMiddleware((to, from) => {
// Executa apenas em navegações do lado do cliente
if (import.meta.client && window.zenovay) {
  window.zenovay('track', 'route_change', {
    from: from.fullPath,
    to: to.fullPath,
  });
}
})

Isso é opcional. O Zenovay já rastreia visualizações de página automaticamente em cada navegação. Use o middleware de rota apenas se precisar anexar dados personalizados a transições específicas.

Modo sem cookies

Para rastreamento respeitoso à privacidade sem cookies ou localStorage, adicione o atributo data-cookieless:

nuxt.config.ts (sem cookies)TypeScript

export default defineNuxtConfig({
app: {
  head: {
    script: [
      {
        defer: true,
        'data-tracking-code': 'YOUR_TRACKING_CODE',
        'data-cookieless': 'true',
        src: 'https://api.zenovay.com/z.js',
      },
    ],
  },
},
})

No modo sem cookies, o Zenovay usa um hash no servidor da sub-rede de IP do visitante, do agente de usuário e de um salt rotacionado diariamente para contar visitantes únicos sem armazenar nada no dispositivo do cliente.

Identificar usuários

Associe dados de analytics a usuários autenticados. Um bom lugar é no seu plugin de autenticação ou layout:

layouts/default.vueVUE

<script setup lang="ts">
const { identify } = useZenovay();
const { data: user } = await useFetch('/api/auth/user');

watch(user, (u) => {
if (u) {
  identify(u.id, {
    email: u.email,
    plan: u.plan,
  });
}
}, { immediate: true });
</script>

<template>
<div>
  <NuxtPage />
</div>
</template>

Rastrear metas e receita

Rastreamento de metas e receitaTypeScript

const { trackGoal, trackRevenue } = useZenovay();

// Rastrear uma meta de conversão
trackGoal('newsletter_signup', { source: 'footer' });

// Rastrear uma compra
trackRevenue(49.99, 'USD');

Suporte a TypeScript

Adicione declarações de tipo para a função global zenovay. O Nuxt inclui automaticamente arquivos *.d.ts da raiz do projeto:

types/zenovay.d.tsTypeScript

declare global {
interface Window {
  zenovay?: (...args: any[]) => void;
}
}

export {};

Configuração baseada em ambiente

Use a configuração de runtime para alternar códigos de rastreamento entre ambientes:

nuxt.config.ts (com runtime config)TypeScript

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

plugins/zenovay.client.ts (dinâmico)TypeScript

export default defineNuxtPlugin(() => {
const config = useRuntimeConfig();
const trackingCode = config.public.zenovayTrackingCode;

if (!trackingCode || typeof document === 'undefined') return;

const script = document.createElement('script');
script.defer = true;
script.dataset.trackingCode = trackingCode;
script.src = 'https://api.zenovay.com/z.js';
document.head.appendChild(script);
})

Em seguida, defina NUXT_PUBLIC_ZENOVAY_TRACKING_CODE no seu ambiente para substituir o valor padrão.

Próximos passos

Seu app Nuxt está agora sendo rastreado pelo Zenovay! Veja seus dados de analytics no painel.

Continue aprendendo:

Eventos personalizados - Padrões avançados de rastreamento de eventos
Metas - Configurar metas de conversão
Conformidade com privacidade - Configuração GDPR e CCPA
Frameworks personalizados - Guia de integração genérico