Saltar al contenido principal
Zenovaydocs
7 min de lectura

Añadir Zenovay Analytics a Nuxt

Zenovay Analytics encaja perfectamente con Nuxt, ofreciendo a los desarrolladores de Vue una forma rápida y respetuosa con la privacidad para rastrear visitantes en aplicaciones Nuxt con renderizado en servidor, generación estática e híbridas. La integración tarda unos dos minutos: añada el script de seguimiento a través de nuxt.config.ts o como un plugin del lado del cliente, y Zenovay comenzará a registrar páginas vistas, referencias, datos del navegador y estadísticas geográficas en tiempo real. El rastreador pesa menos de 1 KB, se carga de forma asíncrona para proteger sus Core Web Vitals y detecta automáticamente los cambios de ruta del lado del cliente a través de Vue Router. Esta guía cubre el enfoque basado en la configuración y el enfoque mediante plugins, además del seguimiento de eventos personalizados con composables, identificación de usuarios, modo sin cookies compatible con el RGPD y consideraciones específicas de renderizado en servidor en Nuxt 3.

Configuración rápida (2 minutos)

Hay dos formas de añadir Zenovay a Nuxt. Elija la que mejor se adapte a su proyecto.

Paso 1: Obtenga su código de seguimiento

Inicie sesión en su panel de Zenovay y copie su código de seguimiento desde Settings → Tracking Code.

Opción A: nuxt.config.ts (Recomendado)

El enfoque más sencillo. Añada el script a app.head en su configuración de 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',
      },
    ],
  },
},
})

¡Listo! Zenovay rastreará automáticamente las páginas vistas en todas sus rutas de Nuxt, incluidas las navegaciones del lado del cliente.

Opción B: Plugin del lado del cliente

Si prefiere más control, cree un plugin de Nuxt que cargue el script en el 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);
})

El sufijo .client.ts garantiza que este plugin solo se ejecute en el navegador, nunca durante el SSR.

Paso 2: Verificar la instalación

Inicie su servidor de desarrollo con npx nuxi dev, visite una página y compruebe el panel de Zenovay. Debería ver un visitante en tiempo real en cuestión de segundos.

Seguimiento de navegación en SPA

Nuxt utiliza Vue Router para el enrutamiento del lado del cliente. Zenovay detecta automáticamente los cambios de ruta a través de la History API (pushState / popstate), por lo que cada navegación registra una nueva página vista sin ninguna configuración adicional.

Esto funciona con:

  • Componentes <NuxtLink>
  • Navegación programática con navigateTo()
  • Llamadas a useRouter().push()
  • Botones de avance/retroceso del navegador

Eventos personalizados con composables

Cree un composable reutilizable para llamadas de análisis limpias en toda su aplicación:

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 };
}

Nuxt importa automáticamente los composables del directorio composables/, por lo que puede utilizarlos en cualquier lugar sin una declaración de importación:

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>

Seguimiento de eventos en 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>

Consideraciones sobre el renderizado en servidor

Nuxt 3 renderiza páginas en el servidor por defecto. El script de Zenovay se ejecuta completamente en el cliente, así que tenga en cuenta estas reglas:

  • Nunca llame a window.zenovay en middleware del servidor, rutas API o archivos server/
  • Siempre proteja las llamadas del lado del cliente con import.meta.client o process.client
  • El script head en nuxt.config.ts es seguro porque el navegador gestiona la carga del script
  • Utilice el sufijo .client.ts para plugins que necesiten el objeto window
Seguridad con SSRTypeScript
// ✅ Seguro: protegido con import.meta.client
if (import.meta.client && window.zenovay) {
window.zenovay('track', 'page_view');
}

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

// ❌ Inseguro: se ejecuta durante el SSR — ¡lanzará un error!
// window.zenovay('track', 'page_view');

Seguimiento con middleware de ruta

Rastree transiciones de ruta específicas con el middleware de rutas de Nuxt:

middleware/analytics.global.tsTypeScript
export default defineNuxtRouteMiddleware((to, from) => {
// Solo se ejecuta en navegaciones del lado del cliente
if (import.meta.client && window.zenovay) {
  window.zenovay('track', 'route_change', {
    from: from.fullPath,
    to: to.fullPath,
  });
}
})

Esto es opcional. Zenovay rastrea automáticamente las páginas vistas en cada navegación. Utilice el middleware de ruta solo si necesita adjuntar datos personalizados a transiciones específicas.

Modo sin cookies

Para un seguimiento respetuoso con la privacidad sin cookies ni localStorage, añada el atributo data-cookieless:

nuxt.config.ts (sin 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',
      },
    ],
  },
},
})

En el modo sin cookies, Zenovay utiliza un hash del lado del servidor de la subred IP del visitante, el agente de usuario y una sal rotativa diaria para contar visitantes únicos sin almacenar nada en el dispositivo del cliente.

Identificar usuarios

Asocie los datos de análisis con los usuarios autenticados. Un buen lugar es en su plugin de autenticación o en el 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>

Seguimiento de objetivos e ingresos

Seguimiento de objetivos e ingresosTypeScript
const { trackGoal, trackRevenue } = useZenovay();

// Rastrear un objetivo de conversión
trackGoal('newsletter_signup', { source: 'footer' });

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

Soporte para TypeScript

Añada declaraciones de tipo para la función global zenovay. Nuxt incluye automáticamente los archivos *.d.ts de la raíz del proyecto:

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

export {};

Configuración basada en entorno

Utilice la configuración de tiempo de ejecución para cambiar los códigos de seguimiento entre entornos:

nuxt.config.ts (con configuración de tiempo de ejecución)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);
})

A continuación, configure NUXT_PUBLIC_ZENOVAY_TRACKING_CODE en su entorno para reemplazar el valor predeterminado.

Siguientes pasos

¡Su aplicación Nuxt ya está rastreando con Zenovay! Vea sus análisis en el panel de control.

Continúe aprendiendo:

¿Fue útil esta página?