10 Min. Lesedauer

Fehlerbehebung

Diese Anleitung behandelt häufige Probleme, auf die Sie bei der Verwendung von Zenovay stoßen können, und wie Sie diese beheben.

Probleme mit Tracking-Skript

Skript wird nicht geladen

Symptome: Keine Daten erscheinen im Dashboard nach der Installation des Tracking-Skripts.

Mögliche Ursachen & Lösungen:

1. Skript nicht korrekt installiert

Überprüfen Sie, ob das Skript im <head>-Bereich Ihrer Seite vorhanden ist:

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

Überprüfen Sie:

Die Skript-URL ist korrekt
Ihr data-tracking-code stimmt mit dem Code in Ihren Domain-Tracking-Skript-Einstellungen überein
Das Skript wird vor dem schließenden </head>-Tag geladen

2. Content Security Policy (CSP) blockiert

Wenn Sie einen CSP-Header haben, fügen Sie Zenovay zu Ihrer Allowlist hinzu:

Content-Security-Policy: script-src 'self' https://api.zenovay.com; connect-src 'self' https://api.zenovay.com;

3. Ad Blocker oder Datenschutzerweiterung

Einige Browser-Erweiterungen können Analytics-Skripte blockieren. Um dies zu überprüfen:

Öffnen Sie DevTools (F12)
Überprüfen Sie den Console-Tab auf blockierte Anfragen
Testen Sie in einem Inkognito-Fenster ohne Erweiterungen

Im Gegensatz zu traditionellen Analytics ist Zenovay datenschutzfreundlich und cookie-frei, sodass es weniger wahrscheinlich von Datenschutz-Tools blockiert wird.

Skript wird geladen, aber keine Daten

Symptome: Skript wird erfolgreich geladen, aber das Dashboard zeigt keine Besucher.

Lösungen:

Browser-Konsole überprüfen

Öffnen Sie DevTools Console und suchen Sie nach Fehlern:

// Sie sollten dies sehen, wenn es korrekt funktioniert
[Zenovay] Tracking initialized for site: abc123
[Zenovay] Pageview tracked successfully

Netzwerkanfragen überprüfen

Öffnen Sie DevTools → Network-Tab
Filtern Sie nach "zenovay" oder "api.zenovay.com"
Suchen Sie nach POST-Anfragen an /e/YOUR_TRACKING_CODE
Überprüfen Sie, ob Anfragen 200 OK oder Fehlercodes zurückgeben

Häufige Fehlercodes:

Statuscode	Bedeutung	Lösung
401	Ungültige Site-ID	Überprüfen Sie Ihren `data-tracking-code` erneut
403	Von Firewall blockiert	Überprüfen Sie CSP-Header oder Firewall-Regeln
429	Rate Limiting	Zu viele Anfragen, warten und erneut versuchen
500	Serverfehler	Kontaktieren Sie Support, wenn das Problem anhält

Probleme mit der Skriptplatzierung

Zenovay erkennt automatisch häufige Installationsfehler und zeigt Warnungen in der Browser-Konsole an. Sie sehen auch Diagnosen im Dashboard, wenn Sie auf Verify Installation klicken.

Wo das Skript platziert werden soll:

Platzieren Sie das Zenovay-Skript immer im <head>-Bereich Ihres HTML mit dem defer-Attribut:

Korrekte PlatzierungHTML

<head>
<!-- Andere head-Tags -->
<script defer data-id="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
</head>

Häufige Fehler:

Fehler	Problem	Lösung
Skript im `<body>`	Kann erste Seitenaufrufe vermissen, lädt zu spät	In den `<head>` verschieben
Skript am Ende des `<body>`	Seite wird vollständig geladen, bevor der Tracker läuft	In den `<head>` verschieben
Fehlendes `defer`	Blockiert das Seitenrendering	Fügen Sie das `defer`-Attribut hinzu
Doppelte Skripte	Erhöht Seitenaufrufe und Metriken	Entfernen Sie zusätzliche Skript-Tags
Falsche `data-id`	Ereignisse werden an die falsche Website gesendet	Kopieren Sie das Snippet von Domains → Ihre Site → General

Framework-spezifische Anleitung:

React: Verwenden Sie useEffect in Ihrer Root-App-Komponente, oder fügen Sie zu public/index.html <head> hinzu
Next.js (App Router): Verwenden Sie die <Script>-Komponente in app/layout.tsx mit strategy="afterInteractive"
Next.js (Pages Router): Fügen Sie in pages/_document.tsx innerhalb von <Head> hinzu
Vue: Fügen Sie zu public/index.html <head>-Bereich hinzu
WordPress: Verwenden Sie "Insert Headers and Footers"-Plugin → Scripts in Header
Shopify: Fügen Sie zu theme.liquid vor </head> hinzu

Probleme mit First-Party-Proxy:

Wenn Sie einen First-Party-Proxy verwenden (z. B. /api/_z/script.js):

Überprüfen Sie, ob die Proxy-URL eine 200-Antwort zurückgibt (nicht 404)
Überprüfen Sie, dass der Proxy den X-Zenovay-Real-IP-Header weiterleitet
Versuchen Sie, https://api.zenovay.com/z.js direkt zu laden, um Proxy vs. Skript-Probleme zu isolieren
Stellen Sie sicher, dass die Content-Security-Policy Ihres Servers Verbindungen zu api.zenovay.com zulässt

Konsolen-Diagnose:

Wenn es Installationsprobleme gibt, sehen Sie Meldungen wie:

⚠️ [Zenovay] Installation issue: Script should be in <head> for accurate tracking. Currently in <body>.
   → Fix: Move the <script> tag into your website's <head> section.
   → Docs: https://docs.zenovay.com/guides/troubleshooting#script-placement

Diese Warnungen erscheinen einmal pro Browser-Sitzung und sollen Ihnen helfen, Ihr Setup zu korrigieren.

Ereignisse werden nicht verfolgt

Symptome: Seitenaufrufe funktionieren, aber benutzerdefinierte Ereignisse erscheinen nicht.

Überprüfen Sie die Ereignissyntax:

// Korrekt
window.zenovay('track', 'button_click', {
  button_name: 'signup',
  page: '/pricing'
});

// Falsch (fehlender Ereignisname)
window.zenovay('track',{
  button_name: 'signup'
});

Überprüfen Sie, ob das Skript geladen wurde:

// Überprüfen Sie, ob Zenovay verfügbar ist
if (window.zenovay) {
  console.log('Zenovay loaded');
  window.zenovay('track', 'custom_event');
} else {
  console.error('Zenovay not loaded yet');
}

Verwenden Sie Ready-Callback:

window.addEventListener('zenovay:ready', function() {
  // Zenovay ist jetzt bereit
  window.zenovay('track', 'page_load_complete');
});

Dashboard-Probleme

Daten werden nicht aktualisiert

Symptome: Dashboard zeigt alte Daten oder wird nicht in Echtzeit aktualisiert.

Lösungen:

1. Browser-Cache löschen

Drücken Sie Ctrl+Shift+R (Windows/Linux) oder Cmd+Shift+R (Mac), um einen hart-Refresh durchzuführen.

2. Datumsbereich überprüfen

Stellen Sie sicher, dass die Datumbereichs-Auswahl den korrekten Zeitraum anzeigt:

Klicken Sie auf die Datumbereichs-Dropdown
Wählen Sie "Heute" oder "Letzte 24 Stunden"
Überprüfen Sie die Zeitzone in Settings → Account → Preferences

3. Verarbeitung abwarten

Echtzeitdaten erscheinen normalerweise innerhalb von 1-2 Sekunden, aber:

Aggregierte Metriken können 5-10 Minuten dauern
Historische Berichte werden stündlich aktualisiert

Null Besucher angezeigt

Symptome: Dashboard zeigt "0 Besucher" trotz Traffic auf Ihrer Website.

Diagnoseschritte:

Site-ID überprüfen: Öffnen Sie Domains → Ihre Site → General und bestätigen Sie, dass der Tracking-Code mit dem in Ihrem Skript übereinstimmt
Filter überprüfen: Entfernen Sie aktive Filter (Standort, Gerät, Quelle)
Lokal testen: Besuchen Sie Ihre Website und überprüfen Sie, ob Sie in der Echtzeitansicht angezeigt werden
Ausschlüsse überprüfen: Öffnen Sie Ihre Domain-Einstellungen und überprüfen Sie die Ausschluss-Konfiguration, um zu sehen, ob Ihre IP ausgeschlossen ist

Standardmäßig schließt Zenovay localhost und 127.0.0.1 aus dem Tracking aus, um zu vermeiden, dass Entwicklungs-Traffic gezählt wird.

Falsche Besucherzahlen

Symptome: Besucherzahlen stimmen nicht mit Erwartungen oder anderen Analytics-Tools überein.

Häufige Gründe:

1. Unterschiede in Definitionen

Zenovay zählt:

Eindeutige Besucher: Basierend auf anonymisierter Besucher-ID (24-Stunden-Fenster)
Besuche: Separate Sitzungen (30-Minuten-Timeout)
Seitenaufrufe: Jedes Laden einer Seite

Andere Tools verwenden möglicherweise unterschiedliche Definitionen oder Sitzungs-Timeouts.

2. Auswirkung von Ad Blockern

Einige Besucher verwenden Ad Blocker, die möglicherweise:

Traditionelle Analytics blockieren, aber nicht Zenovay (datenschutzfreundlich)
Alle Analytics blockieren, einschließlich Zenovay (aggressive Einstellungen)

3. Bot-Filterung

Zenovay filtert automatisch bekannte Bots und Crawler. Andere Tools können:

Bot-Traffic in den Zählungen einschließen
Unterschiedliche Bot-Erkennungsmethoden verwenden

Integrationsprobleme

WordPress-Plugin funktioniert nicht

Symptome: WordPress-Integration verfolgt Besucher nicht.

Lösungen:

1. Überprüfen Sie die Plugin-Installation

Gehen Sie zu Plugins → Installierte Plugins
Stellen Sie sicher, dass "Zenovay Analytics" aktiviert ist
Überprüfen Sie, dass Version die neueste ist

2. Überprüfen Sie die Site-ID-Konfiguration

Gehen Sie zu Settings → Zenovay
Überprüfen Sie, dass Site-ID korrekt eingegeben ist
Speichern Sie Änderungen und leeren Sie Cache

3. Theme-Kompatibilität

Einige Themes können mit Header/Footer-Injektion in Konflikt geraten:

// Fügen Sie zu functions.php Ihres Themes als Fallback hinzu
function zenovay_tracking_script() {
  ?>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
  <?php
}
add_action('wp_head', 'zenovay_tracking_script');

4. Caching-Plugin-Konflikte

Wenn Sie WP Super Cache, W3 Total Cache oder ähnliches verwenden:

Leeren Sie alle Caches
Schließen Sie Zenovay-Skript von Minifizierung/Kombinierung aus
Testen Sie im Inkognito-Modus

React/SPA verfolgt Route-Änderungen nicht

Symptome: Nur das initiale Laden der Seite wird verfolgt, Route-Änderungen werden nicht gezählt.

Lösung: Implementieren Sie Client-seitiges Route-Tracking:

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Track route changes
    if (window.zenovay) {
      window.zenovay('track', 'pageview', {
        path: location.pathname + location.search
      });
    }
  }, [location]);

  return <YourApp />;
}

Für Next.js App Router:

'use client';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function AnalyticsTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    if (window.zenovay) {
      window.zenovay('track', 'pageview');
    }
  }, [pathname, searchParams]);

  return null;
}

API-Probleme

Authentifizierungsfehler

Symptome: API-Anfragen geben 401 Unauthorized zurück.

Überprüfen Sie API-Schlüssel:

# Testen Sie Ihren API-Schlüssel
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Häufige Fehler:

Verwendung von Site-ID anstelle von API-Schlüssel
Fehlender X-API-Key-Header
API-Schlüssel abgelaufen oder widerrufen
Falscher API-Schlüssel für Umgebung (Test vs. Produktion)

Generieren Sie einen neuen API-Schlüssel:

Gehen Sie zu Settings → Security → API keys
Klicken Sie auf "Create New Key"
Kopieren Sie den Schlüssel sofort (wird nur einmal angezeigt)
Ersetzen Sie den alten Schlüssel in Ihrer Anwendung

Rate Limiting

Symptome: API gibt 429 Too Many Requests zurück.

Überprüfen Sie Rate-Limit-Header:

curl -I -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Suchen Sie nach:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1673456789

Der X-RateLimit-Limit-Wert spiegelt das Pro-Minute-Limit Ihres Plans wider (z. B. 10 für Free, 30 für Pro, 60 für Scale, 120 für Enterprise).

Lösungen:

Implementieren Sie exponentiellen Backoff (siehe Rate Limits)
Cache-API-Antworten, wo möglich
Batch-Anfragen anstelle einzelner Aufrufe
Erwägen Sie ein Upgrade Ihres Plans für höhere Limits

Leistungsprobleme

Skript verlangsamt das Laden der Seite

Symptome: Seitenladezeiten haben sich nach dem Hinzufügen von Zenovay erhöht.

Überprüfen Sie asynchrones Laden:

Stellen Sie sicher, dass das Skript das async-Attribut hat:

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

Überprüfen Sie Auswirkungen:

Verwenden Sie Browser DevTools oder Lighthouse:

Führen Sie Lighthouse-Audit mit und ohne Skript aus
Vergleichen Sie "Time to Interactive"-Metriken
Überprüfen Sie "Blocking Time"

Das Zenovay-Skript ist normalerweise < 5KB gzipped und lädt asynchron, wodurch < 50ms zur Seitenladezeit hinzugefügt wird.

Dashboard lädt langsam

Symptome: Dashboard braucht lange zum Laden von Diagrammen und Daten.

Lösungen:

1. Datumsbereich reduzieren

Das Laden von 12 Monaten Daten ist langsamer als 7 Tage:

Verwenden Sie kürzere Datumsbereiche, wenn möglich
Wenden Sie Filter an, um Datenvolumen zu reduzieren

2. Browser-Daten löschen

Löschen Sie Browser-Cache und Cookies
Deaktivieren Sie Browser-Erweiterungen, die möglicherweise interferieren
Versuchen Sie einen anderen Browser

3. Überprüfen Sie Netzwerk

Testen Sie Ihre Internet-Verbindungsgeschwindigkeit
Versuchen Sie ein anderes Netzwerk
Überprüfen Sie, ob Corporate Firewall drosselt

Probleme mit Datengenauigkeit

Fehlende geografische Daten

Symptome: Einige Besucher zeigen "Unknown"-Standort.

Ursachen:

VPN- oder Proxy-Verwendung durch Besucher
Datenschutz-orientierte Browser, die Standort maskieren
Corporate Networks mit zentralisierten IP-Adressen

Dies ist erwartetes Verhalten und betrifft 5-15% der Besucher je nach Publikum.

Referrer zeigt sich als "Direct"

Symptome: Der meiste Traffic zeigt sich als "Direct" anstelle der tatsächlichen Quelle.

Häufige Ursachen:

1. HTTPS → HTTP Übergänge

Referrer wird entfernt beim Übergang von HTTPS zu HTTP. Lösung: Verwenden Sie HTTPS auf Ihrer Website.

2. Referrer Policy

Einige Websites verwenden strenge Referrer-Richtlinien:

<meta name="referrer" content="no-referrer">

Dies ist die Richtlinie der sendenden Website, nicht etwas, das Sie kontrollieren können.

3. Mobile Apps und E-Mail

Traffic von mobilen Apps und E-Mail-Clients zeigt sich häufig als Direct - dies ist normal und erwartet.

Hilfe bekommen

Wenn Sie nach dem Versuch dieser Lösungen noch Probleme haben:

Überprüfen Sie Service-Status

Besuchen Sie status.zenovay.com, um zu sehen, ob es einen bekannten Ausfall oder Incident gibt.

Diagnostische Informationen sammeln

Bevor Sie Support kontaktieren, sammeln Sie:

Browser Console-Logs:
- Öffnen Sie DevTools → Console
- Kopieren Sie alle Fehlermeldungen
- Machen Sie einen Screenshot
Netzwerkanfragen:
- Öffnen Sie DevTools → Network
- Filtern Sie nach "zenovay"
- Machen Sie einen Screenshot fehlgeschlagener Anfragen mit Statuscodes
Website-Informationen:
- Ihre Website-URL
- Site-ID vom Dashboard
- Plattform/CMS (WordPress, custom, etc.)
- Ungefähres Traffic-Volumen

Support kontaktieren

E-Mail: [email protected]

Fügen Sie hinzu:

Detaillierte Beschreibung des Problems
Schritte, die Sie bereits versucht haben
Diagnostische Informationen von oben
Screenshots oder Screen Recordings

Antwortzeiten:

Free Plan: 48-72 Stunden
Paid Plans: 24 Stunden
Enterprise: 4 Stunden (SLA)

Community-Hilfe

GitHub: github.com/zenovay
Dokumentation: Suchen Sie unsere Docs nach bestimmten Themen
AI-Assistent: Verwenden Sie das Chat-Widget auf jeder Docs-Seite

Fehlerbehebung

Probleme mit Tracking-Skript

Skript wird nicht geladen

Skript wird geladen, aber keine Daten

Probleme mit der Skriptplatzierung

Ereignisse werden nicht verfolgt

Dashboard-Probleme

Daten werden nicht aktualisiert

Null Besucher angezeigt

Falsche Besucherzahlen

Integrationsprobleme

WordPress-Plugin funktioniert nicht

React/SPA verfolgt Route-Änderungen nicht

API-Probleme

Authentifizierungsfehler

Rate Limiting

Leistungsprobleme

Skript verlangsamt das Laden der Seite

Dashboard lädt langsam

Probleme mit Datengenauigkeit

Fehlende geografische Daten

Referrer zeigt sich als "Direct"

Hilfe bekommen

Überprüfen Sie Service-Status

Diagnostische Informationen sammeln

Support kontaktieren

Community-Hilfe

Zusätzliche Ressourcen