Zum Hauptinhalt springen
Zenovaydocs
6 Min. Lesedauer

Zenovay Analytics zu Nuxt hinzufügen

Diese Anleitung führt Sie durch das Hinzufügen von Zenovay Analytics zu einer Nuxt-3-App. Fügen Sie das Tracking-Skript über nuxt.config.ts oder ein clientseitiges Plugin ein, und Zenovay beginnt, Seitenaufrufe, Referrer, Browserdaten und geografische Erkenntnisse in Echtzeit zu erfassen. Das Tracker-Skript ist unter 1 KB groß, lädt asynchron und erkennt clientseitige Routenänderungen über Vue Router automatisch. Die Anleitung behandelt beide Setup-Ansätze sowie benutzerdefinierte Ereignisverfolgung mit Composables, Benutzeridentifikation, Cookieless-Modus und SSR-Überlegungen für Nuxt 3.

Schnellstart (2 Minuten)

Es gibt zwei Möglichkeiten, Zenovay zu Nuxt hinzuzufügen. Wählen Sie die für Ihr Projekt am besten geeignete.

Schritt 1: Ihren Tracking-Code abrufen

Melden Sie sich bei Ihrem Zenovay-Dashboard an, öffnen Sie Domains → Ihre Website, und kopieren Sie Ihren Tracking-Code von der General-Einstellungsseite.

Tracking-Skript-Karte mit dem Skript-Snippet mit HTML-, React-, Next.js- und First-Party-Tabs und einer Schaltfläche zur Überprüfung der Installation
Die Tracking-Skript-Karte auf der General-Einstellungsseite Ihrer Website. Kopieren Sie das Skript-Tag oder verwenden Sie eines der Framework-Tabs.

Option A: nuxt.config.ts (Empfohlen)

Der einfachste Ansatz. Fügen Sie das Skript zu app.head in Ihrer Nuxt-Konfiguration hinzu:

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

Das war's! Zenovay verfolgt automatisch Seitenaufrufe über alle Ihre Nuxt-Routen, einschließlich clientseitiger Navigationen.

Option B: Clientseitiges Plugin

Wenn Sie mehr Kontrolle bevorzugen, erstellen Sie ein Nuxt-Plugin, das das Skript auf der Clientseite lädt:

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

Das Suffix .client.ts stellt sicher, dass dieses Plugin nur im Browser ausgeführt wird, niemals während des SSR.

Schritt 2: Installation überprüfen

Starten Sie Ihren Entwicklungsserver mit npx nuxi dev, besuchen Sie eine Seite und prüfen Sie das Zenovay-Dashboard. Innerhalb weniger Sekunden sollte ein Echtzeit-Besucher erscheinen.

SPA-Navigationsverfolgung

Nuxt verwendet Vue Router für clientseitiges Routing. Zenovay erkennt Routenänderungen automatisch über die History API (pushState / popstate), sodass jede Navigation einen neuen Seitenaufruf ohne jegliche Konfiguration erfasst.

Dies funktioniert mit:

  • <NuxtLink>-Komponenten
  • Programmatischer Navigation mit navigateTo()
  • useRouter().push()-Aufrufen
  • Browser-Vor- und Zurück-Schaltflächen

Benutzerdefinierte Ereignisse mit Composables

Erstellen Sie ein wiederverwendbares Composable für saubere Analytics-Aufrufe in Ihrer gesamten 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 };
}

Nuxt importiert Composables aus dem Verzeichnis composables/ automatisch, sodass Sie sie überall ohne Import-Anweisung verwenden können:

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>

Ereignisse in Komponenten verfolgen

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>

Überlegungen zum serverseitigen Rendering

Nuxt 3 rendert Seiten standardmäßig auf dem Server. Das Zenovay-Skript läuft ausschließlich auf dem Client, daher beachten Sie folgende Regeln:

  • Rufen Sie window.zenovay niemals in Server-Middleware, API-Routen oder server/-Dateien auf
  • Sichern Sie clientseitige Aufrufe immer mit import.meta.client oder process.client ab
  • Das nuxt.config.ts-Head-Skript ist sicher, da der Browser das Laden des Skripts übernimmt
  • Verwenden Sie das Suffix .client.ts für Plugins, die das window-Objekt benötigen
SSR-SicherheitTypeScript
// ✅ Sicher: mit import.meta.client abgesichert
if (import.meta.client && window.zenovay) {
window.zenovay('track', 'page_view');
}

// ✅ Sicher: innerhalb von onMounted (nur clientseitiger Lifecycle-Hook)
onMounted(() => {
if (window.zenovay) {
  window.zenovay('track', 'component_visible');
}
});

// ❌ Unsicher: läuft während SSR — wird einen Fehler auslösen!
// window.zenovay('track', 'page_view');

Routen-Middleware-Verfolgung

Verfolgen Sie spezifische Routenübergänge mit Nuxt-Routen-Middleware:

middleware/analytics.global.tsTypeScript
export default defineNuxtRouteMiddleware((to, from) => {
// Läuft nur bei clientseitigen Navigationen
if (import.meta.client && window.zenovay) {
  window.zenovay('track', 'route_change', {
    from: from.fullPath,
    to: to.fullPath,
  });
}
})

Dies ist optional. Zenovay verfolgt Seitenaufrufe bei jeder Navigation automatisch. Verwenden Sie Routen-Middleware nur, wenn Sie benutzerdefinierte Daten an bestimmte Übergänge anhängen müssen.

Cookieless-Modus

Für datenschutzfreundliches Tracking ohne Cookies oder localStorage fügen Sie das Attribut data-cookieless hinzu:

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

Im Cookieless-Modus verwendet Zenovay eine in-memory, window-scoped Besucher-ID, die nur für die aktuelle Sitzung existiert. Keine Cookies, kein localStorage und keine Daten werden auf dem Clientgerät geschrieben. Die ID wird verworfen, wenn die Seite entladen wird.

Benutzer identifizieren

Verknüpfen Sie Analytics-Daten mit authentifizierten Benutzern. Ein guter Platz dafür ist Ihr Auth-Plugin oder 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>

Ziele und Umsatz verfolgen

Ziel- und UmsatzverfolgungTypeScript
const { trackGoal, trackRevenue } = useZenovay();

// Konversionsziel verfolgen
trackGoal('newsletter_signup', { source: 'footer' });

// Kauf verfolgen
trackRevenue(49.99, 'USD');

TypeScript-Unterstützung

Fügen Sie Typdeklarationen für die globale zenovay-Funktion hinzu. Nuxt bezieht *.d.ts-Dateien aus dem Projektstamm automatisch ein:

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

export {};

Umgebungsbasierte Konfiguration

Verwenden Sie Runtime-Konfiguration, um Tracking-Codes zwischen Umgebungen auszutauschen:

nuxt.config.ts (mit Runtime-Konfiguration)TypeScript
export default defineNuxtConfig({
runtimeConfig: {
  public: {
    zenovayTrackingCode: 'YOUR_TRACKING_CODE',
  },
},
})
plugins/zenovay.client.ts (dynamisch)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);
})

Setzen Sie dann NUXT_PUBLIC_ZENOVAY_TRACKING_CODE in Ihrer Umgebung, um den Standard zu überschreiben.

Nächste Schritte

Ihre Nuxt-App verfolgt nun mit Zenovay! Sehen Sie Ihre Analytics im Dashboard ein.

Vertiefen Sie Ihr Wissen:

War diese Seite hilfreich?