Localhost-Tests

Standardmäßig blockiert Zenovay das Tracking auf localhost und anderen lokalen Umgebungen, um zu verhindern, dass Testdaten deine Analysen verunreinigen. Du kannst das lokale Tracking für Entwicklung und Tests aktivieren.

Localhost-Tracking aktivieren

Option 1: Dashboard-Toggle (Empfohlen)

1. Gehe zu deinem Zenovay-Dashboard
2. Öffne Domains und klicke auf deine Website
3. Öffne in den Domain-Einstellungen den Bereich Advanced
4. Aktiviere den Toggle "Allow Localhost"
5. Klicke auf Speichern

Option 2: Script-Attribut

Wenn du dies lieber umgebungsspezifisch über deinen HTML-Code steuern möchtest, füge data-allow-localhost="true" zum Script-Tag hinzu:

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
data-allow-localhost="true"
src="https://api.zenovay.com/z.js">
</script>

Hinweis: Die Dashboard-Einstellung oben ist die maßgebliche Steuerung. Der Server akzeptiert Localhost-Events nur, wenn sie aktiviert ist, und der Einstellungs-Abruf des Trackers hat Vorrang vor diesem Attribut. Behalte das Attribut für die Offline-Entwicklung (wenn der Einstellungs-Abruf nicht möglich ist); auf Produktions-Domains hat es keine Wirkung.

Option 3: Dynamisches Script-Laden

Für Frameworks wie React oder Next.js, bei denen du das Script dynamisch lädst:

const script = document.createElement('script');
script.src = 'https://api.zenovay.com/z.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

So funktioniert es

Zenovay erkennt lokale Umgebungen, indem es den Hostnamen überprüft:

Wenn eine lokale Umgebung erkannt wird, überprüft der Tracker zwei Dinge (der Reihe nach):

1. Server-Einstellungen — Der Tracker lädt deine Website-Konfiguration von der Zenovay-API. Wenn allow_localhost im Dashboard aktiviert ist, wird das Tracking fortgesetzt.
2. Script-Attribut — Wenn der API-Aufruf fehlschlägt oder noch nicht abgeschlossen ist, dient das data-allow-localhost="true"-Attribut auf dem Script-Tag als Fallback.

Wenn beides nicht gesetzt ist, wird das Tracking blockiert und du siehtst diese Nachricht in der Browser-Konsole:

[Zenovay] Environment blocked — Localhost blocked (use data-allow-localhost='true' to enable)

Überprüfe, ob es funktioniert

Browser-Konsole

Öffne die DevTools (F12) → Reiter Konsole. Mit aktiviertem Localhost-Tracking solltest du sehen:

Zenovay Analytics loaded { trackingCode: "ZV_...", reason: "Active" }

Wenn Localhost blockiert ist, siehtst du:

[Zenovay] Environment blocked { reason: "Localhost blocked (use data-allow-localhost='true' to enable)" }

Netzwerk-Reiter

Öffne DevTools → Reiter Netzwerk und filtere nach zenovay oder api.zenovay.com:

1. GET z.js — Script wird geladen (200 OK)
2. GET /api/websites/settings/ZV_... — Einstellungen abrufen (200 OK, Antwort enthält allow_localhost: true)
3. POST /e/ZV_... — Seitenaufruf-Ereignis verfolgt (200 OK)

Wenn Schritt 3 403 zurückgibt, blockiert deine Domain-Verifizierung die Anfrage. Stelle sicher, dass allow_localhost in deinen Dashboard-Einstellungen aktiviert ist.

Dashboard

Nach einem Seitenaufruf auf Localhost gehe zu deinem Zenovay-Dashboard. Öffne Domains, wähle deine Website aus und öffne den Reiter Analytics. In der Hosts-Aufschlüsselung solltest du localhost (oder 127.0.0.1) als Quelle sehen.

Debug Mode vs Allow Localhost

Dies sind zwei separate Einstellungen mit unterschiedlichen Zwecken:

Du kannst während der Entwicklung beide aktivieren, um maximale Sichtbarkeit zu erhalten, aber sie funktionieren unabhängig voneinander.

• Allow Localhost kontrolliert nur, ob Tracking auf Localhost läuft
• Debug Mode kontrolliert nur, ob Debug-Ausgabe in der Konsole angezeigt wird

Mit dem Load-Endpunkt verwenden

Wenn du den /load-Endpunkt verwendest (empfohlen für Produktion), werden Localhost-Einstellungen automatisch vom Server eingespritzt:

<script defer
data-tracking-code="YOUR_TRACKING_CODE"
src="https://api.zenovay.com/load/YOUR_TRACKING_CODE">
</script>

Mit dem /load-Endpunkt musst du nur "Allow Localhost" im Dashboard aktivieren — das data-allow-localhost-Attribut ist nicht erforderlich.

First-Party Proxy auf Localhost

Wenn dein Produktions-Setup einen First-Party Proxy verwendet (z.B. /api/_z/script.js), funktioniert der Proxy normalerweise nicht auf localhost, da es eine serverseitige Route ist, die zu api.zenovay.com weitergeleitet wird.

Lösungen:

1. Verwende das direkte Script auf Localhost: Wechsle in der Entwicklung zu https://api.zenovay.com/z.js
2. Richte einen lokalen Proxy ein: Konfiguriere deinen Dev-Server, um /api/_z/ zu https://api.zenovay.com/ zu proxieren
3. Verwende eine umgebungsbasierte Script-URL: Lade von deinem Proxy in der Produktion, direkt in der Entwicklung

const isDev = window.location.hostname === 'localhost';
const script = document.createElement('script');
script.src = isDev
? 'https://api.zenovay.com/z.js'
: '/api/_z/script.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
if (isDev) script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

Fehlerbehebung

Tracking funktioniert nicht auf Localhost

1. Überprüfe die Dashboard-Einstellung: Öffne Domains, wähle deine Website aus, öffne den Bereich Advanced und verifiziere, dass "Allow Localhost" aktiviert ist
2. Hard Refresh: Änderungen können bis zu 30 Sekunden dauern. Führe Ctrl+Shift+R aus, um gecachte Scripts zu löschen
3. Überprüfe die Konsole: Öffne DevTools und suche nach [Zenovay]-Meldungen
4. Verifiziere, dass das Script geladen wird: Überprüfe den Netzwerk-Reiter für z.js, das 200 zurückgibt
5. Überprüfe auf Ad-Blocker: Browser-Erweiterungen können Analysen sogar auf Localhost blockieren

Ereignisse geben 403 zurück

Die API lehnte deine Tracking-Anfrage aufgrund der Domain-Verifizierung ab. Dies bedeutet:

• allow_localhost ist nicht in deinen Website-Einstellungen aktiviert, ODER
• Die Einstellung hat sich noch nicht propagiert (warte 30 Sekunden und versuche es erneut)

Ereignisse werden ausgelöst, aber Daten erscheinen nicht im Dashboard

Localhost-Daten erscheinen in deinen Analysen neben Produktionsdaten. Überprüfe:

• Reiter Hosts in Analytics — suche nach localhost-Einträgen
• Filter — stelle sicher, dass du localhost-Traffic nicht filterst
• Zeitbereich — stelle sicher, dass du Daten von heute anschaust