8 Min. Lesedauer

Debug-Overlay

Ein schwebendes In-Page-Overlay, das jedes Ereignis, das Ihr Zenovay-Tracker sendet, in Echtzeit darstellt — Typ, Eigenschaften, Cookieless-Modus, GPC-Status, Einwilligungsstatus und Skript-Version — ohne dass Sie die Browser-DevTools öffnen müssen. PII werden maskiert. Das Overlay ist doppelt abgesichert: Es wird nur aktiviert, wenn Sie es auf der Einstellungsseite der Website aktiviert und zusätzlich ?zenovay_debug=1 an eine URL Ihrer Website angehängt haben.

Beide Schalter sind erforderlich. Das alleinige Aktivieren der Website-Einstellung bewirkt nichts. Das alleinige Anhängen von ?zenovay_debug=1 bewirkt nichts. Beide Bedingungen müssen beim selben Seitenaufruf zutreffen. Dadurch wird eine versehentliche Sichtbarkeit für reguläre Besucher verhindert.

Wozu es dient

Beim Verifizieren einer Installation — lokale Entwicklung, Staging oder ein Produktions-Smoketest — möchten Sie meist nur eine Tatsache wissen: „Sendet der Tracker die richtigen Ereignisse mit den richtigen Eigenschaften?" Die klassische Antwort lautet: DevTools öffnen → Tab Network → nach /e/ oder /api/_z filtern → jede Anfrage anklicken → den JSON-Body lesen. Das Debug-Overlay reduziert diesen Vorgang auf einen einzigen Blick: Jedes Ereignis, das der Tracker sendet, erscheint als Zeile, ein Klick auf eine beliebige Zeile zeigt das vollständige JSON, mit „Copy JSON" lässt es sich für ein Support-Ticket einfügen.

Außerdem ist es nützlich beim Onboarding neuer Teammitglieder („so sieht genau das aus, was wir senden") und für die Dokumentation beabsichtigten Verhaltens (machen Sie einen Screenshot des Overlays während eines bekannten korrekten Nutzerflusses und legen Sie ihn als Regressions-Baseline ab).

Aktivieren

Melden Sie sich bei app.zenovay.com an und öffnen Sie die Seite Domains.
Klicken Sie auf die Domain, die Sie debuggen möchten.
Öffnen Sie Einstellungen → Erweitert und scrollen Sie zum Abschnitt Basis-Einstellungen.
Schalten Sie Allow Debug Overlay ein.
Rufen Sie auf Ihrer eigenen Website eine beliebige URL mit angehängtem ?zenovay_debug=1 auf — zum Beispiel https://your-site.com/?zenovay_debug=1 oder https://your-site.com/checkout?zenovay_debug=1.

Das Overlay erscheint etwa eine Sekunde nach dem Laden des Trackers in der unteren rechten Ecke.

Cache-Verteilung: Die Tracker-Konfiguration wird nach dem Umlegen des Schalters bis zu 5 Minuten am Edge zwischengespeichert. Wenn das Overlay nicht sofort erscheint, laden Sie die Seite per Hard-Reload neu (Cmd/Strg + Umschalt + R) oder warten Sie einige Minuten.

Was Sie sehen

Das Overlay besteht aus drei Bereichen:

Header-Chips zeigen den Laufzeitzustand des Trackers auf der aktuellen Seite:

cookieless ON | OFF — ob der Cookieless-Modus für diese Website aktiv ist. ON bedeutet, dass der Tracker im Window-Scope gehaltene In-Memory-IDs verwendet und keinerlei Cookies schreibt. OFF bedeutet, dass cookiebasierte Sitzungs- und Besucher-IDs verwendet werden.
GPC ON | OFF — ob der Browser des Besuchers ein Global Privacy Control-Signal gesendet hat (Sec-GPC: 1 / navigator.globalPrivacyControl === true). Bei ON wird die verhaltensbasierte Anreicherung (B2B, Scoring) auf dem Server übersprungen.
consent: <state> — der zuletzt vom Tracker beobachtete Einwilligungsstatus (opt-in, opt-out, unknown). Wenn Sie eine Consent-Management-Plattform nutzen, spiegelt dieser Wert die Wahl des Besuchers wider.
v<version> — die aktuell auf der Seite ausgeführte Version des Tracker-Skripts.

Ereignisliste zeigt die 20 zuletzt ausgehenden Ereignisse, das neueste oben. Jede Zeile enthält:

Wanduhrzeit-Zeitstempel (HH:MM:SS, Browser-Lokalzeit)
Ereignistyp
Bis zu 4 abgekürzte Eigenschafts-Schlüssel

Klicken Sie auf eine beliebige Zeile, um das JSON-Modal zu öffnen.

JSON-Modal zeigt das vollständige Ereignis-JSON (nach Anwendung der PII-Maskierung). Über die Schaltfläche Copy JSON kopieren Sie es in die Zwischenablage — praktisch zum Teilen mit einem Teammitglied oder als Anhang an ein Support-Ticket.

Ereignistypen verstehen

Ereignistyp	Bedeutung
`pageview`	Eine neue Seite wurde aufgerufen. Enthält URL, Referrer, UTM-Parameter, Geräteklasse und Bildschirmgröße.
`heartbeat`	Der Besucher befindet sich weiterhin auf der Seite. Wird im Leerlauf alle ca. 2 Sekunden ausgelöst, damit die Verweildauer präzise berechnet werden kann.
`page_exit`	Der Besucher hat den Tab geschlossen oder zu einer anderen Seite navigiert. Letzter Wert für die Verweildauer.
`outbound_link`	Klick auf ein `<a>`-Tag, dessen `href` auf eine fremde Domain verweist.
`goal_completion`	Ein konfiguriertes Ziel wurde ausgelöst. Enthält den Zielnamen und etwaige benutzerdefinierte Parameter.
`funnel_step`	Der Besucher hat in einem konfigurierten Funnel den nächsten Schritt erreicht.
`custom_event`	Ein `zenovay.track('event_name', {...})`-Aufruf aus Ihrem eigenen Code.
`error`	Ein vom Tracker erfasster JavaScript-Fehler (wird nur gesendet, wenn Fehler-Tracking in Ihrem Plan aktiviert ist).
`core_web_vitals`	LCP-/CLS-/INP-Messwerte für die aktuelle Seite (werden einmal pro Seite gesendet, sobald sich die Metriken stabilisiert haben).
`session_replay`	Ein Datenpaket der Session-Aufzeichnung wurde hochgeladen. Das Overlay zeigt nur, dass das Paket gesendet wurde — niemals den Inhalt der Aufzeichnung.
`frustration_signal`	Ein Rage-Click, Dead-Click oder übermäßiges Scroll-Jitter wurde erkannt.

PII-Maskierung

Das Overlay wendet eine Anzeige-Maske auf jedes Ereignis an, bevor es auf dem Bildschirm dargestellt wird. Die Maske deckt zwei Fälle ab:

Treffer beim Feldnamen (Schlüssel) — jede Eigenschaft mit einem dieser Schlüsselnamen wird durch [MASKED] ersetzt:

email, phone, first_name, last_name, name, customer_id, user_id, ip, ip_address, client_ip, user_agent, useragent, ua

Mustertreffer beim Wert — wird auch dann angewandt, wenn der Schlüsselname nicht passt:

Zeichenketten, die dem E-Mail-Format entsprechen ([email protected]), werden teilweise unkenntlich gemacht (a***@b***.tld).
Zeichenketten, die einer IPv4-Adresse entsprechen (1.2.3.4), werden durch [IP] ersetzt.
Zeichenketten mit mehr als 80 Zeichen, die Mozilla|WebKit|Chrome|Safari|Firefox enthalten, werden gekürzt und mit [UA truncated] gekennzeichnet.

Die Maskierung erfolgt ausschließlich in der Anzeigeschicht des Overlays. Die rohe Ereignis-Payload, die der Tracker tatsächlich an Zenovay sendet, bleibt unverändert — sie speist Ihre Dashboards. Die Maske wirkt sich nur auf das aus, was Sie auf dem Bildschirm sehen, sodass Screenshots und das Kopieren von JSON aus dem Overlay gefahrlos geteilt werden können.

Datenschutz und Compliance

Das Overlay ist so konzipiert, dass es in jeder Umgebung sicher aktiviert werden kann. Sie sollten dennoch genau verstehen, was es tut und was nicht:

Keine Cookies, kein localStorage. Der Ereignisbus ist ein einfaches JavaScript-Array auf window (window._zenovayDebugBus). Es verschwindet, sobald der Tab geschlossen wird.
Kein Remote-Logging. Das Overlay führt zu keinem Zeitpunkt einen Netzwerkaufruf durch. Alles, was Sie sehen, wird aus bereits im Browser-Speicher vorhandenen Daten gerendert.
Lazy-geladen. Die Overlay-Oberfläche ist eine separate HTTP-Ressource (/debug-overlay.js), die nur dann heruntergeladen wird, wenn beide Schalter erfüllt sind. Besucher ohne den URL-Parameter laden null Overlay-Bytes herunter.
Die Cookieless-Tracker-Invariante bleibt erhalten. Wenn Ihre Website im Cookieless-Modus läuft, ändert das Aktivieren des Overlays das Tracker-Verhalten nicht — es werden keine Cookies geschrieben, es werden weiterhin dieselben temporären Window-Scope-IDs verwendet, und der Cookieless-Chip im Header zeigt ON.
GPC wird in jedem Fall respektiert. Das Overlay liest den GPC-Status aus der Tracker-Konfiguration aus, umgeht ihn aber nicht.

Fehlerbehebung

„Ich habe ?zenovay_debug=1 angehängt und nichts passiert."

Prüfen Sie noch einmal, ob die Website-Einstellung aktiviert ist. Beide Schalter müssen aktiv sein.
Laden Sie die Seite per Hard-Reload neu (Cmd/Strg + Umschalt + R) — die Tracker-Konfiguration wird nach dem Umlegen des Schalters bis zu 5 Minuten zwischengespeichert.
Bestätigen Sie, dass Ihre Tracker-Version das Overlay unterstützt, indem Sie die DevTools öffnen und window.ZENOVAY_TRACKER_CONFIG ausführen — wenn allowDebugOverlay false ist, obwohl der Schalter aktiviert wurde, ist der Cache noch nicht invalidiert.
Stellen Sie sicher, dass keine Content-Security-Policy auf Ihrer Website Skripte von api.zenovay.com blockiert.

„Das Overlay erscheint, aber es werden keine Ereignisse angezeigt."

Lösen Sie auf der Seite eine Interaktion aus (Link anklicken, scrollen, navigieren), damit der Tracker etwas sendet.
Wenn weiterhin nichts erscheint, sendet der Tracker möglicherweise gar nicht — gleichen Sie dies mit dem Installations-Status ab, der denselben Pfad serverseitig prüft.

„Das Overlay verschwindet bei einem SPA-Routenwechsel."

Das Overlay sollte sich bei Routenwechseln automatisch neu mounten. Falls nicht, handelt es sich um einen bekannten Sonderfall bei Frameworks, die document.body-Children aggressiv entfernen — bitte melden Sie eine Reproduktion unter help.zenovay.com.

„Mehrere Zenovay-Tracker auf meiner Seite."

Es wird nur ein einziges Overlay gemountet. Der zuerst initialisierte Tracker gewinnt (window._zenovayDebugOverlayMounted-Schutz).

„Ich sehe [MASKED] für Felder, die ich absichtlich gesendet habe."

Das ist erwartetes Verhalten. Die Maske wird unbedingt auf eine Liste gängiger PII-Schlüsselnamen angewandt. Wenn Sie ein nicht-personenbezogenes Feld mit einem sensibel klingenden Namen anzeigen möchten (z. B. wenn Sie name für ein nicht-personenbezogenes Label verwendet haben), benennen Sie die Eigenschaft um und testen Sie erneut.

„Das Overlay verdeckt einen wichtigen Teil meiner Oberfläche."

Klicken Sie auf das × im Header, um das Overlay bis zum nächsten Seitenaufruf auszublenden.

Wann deaktivieren

Wir empfehlen, den Schalter Debug-Overlay zulassen in der Produktion auszuschalten, sobald Sie Ihre Installation verifiziert haben. Auch wenn die doppelte Absicherung eine versehentliche Sichtbarkeit für gewöhnliche Besucher (die niemals ?zenovay_debug=1 anhängen) verhindert, entfällt durch das Standardmäßig-Deaktiviert-Lassen des Website-seitigen Schalters der zweite Faktor vollständig, wodurch eine versehentliche Sichtbarkeit unmöglich wird — selbst dann, wenn ein Entwickler versehentlich eine Debug-URL teilt.

Browser-Unterstützung

Das Overlay funktioniert in allen Evergreen-Browsern (Chrome, Firefox, Safari, Edge) und scheitert in älteren Browsern ohne URLSearchParams oder mit restriktiver CSP elegant — es löst niemals einen unbehandelten Fehler in der Host-Seite aus.