8 min read

Debug Overlay

A floating, in-page overlay that streams every event your Zenovay tracker is sending — type, props, cookieless mode, GPC state, consent state, and script version — without you having to open browser devtools. PII is masked. The overlay is double-gated: it never activates unless you've opted in on the website settings page and appended ?zenovay_debug=1 to a URL on your site.

Both gates are required. Enabling the website setting alone does nothing. Adding ?zenovay_debug=1 alone does nothing. Both must be true on the same page load. This prevents accidental exposure to general visitors.

Why use it

When verifying an install — local dev, staging, or production smoke test — you usually want one fact: "is the tracker firing the right events with the right props?" The traditional answer is: open devtools → Network tab → filter for /e/ or /api/_z → click each request → read the JSON body. The debug overlay collapses that into a glance: every event the tracker sends shows up as a row, click any row to see the full JSON, click "Copy JSON" to paste it into a support ticket.

It's also useful for onboarding new teammates ("here's exactly what we send") and for documentation of intentional behavior (record a screenshot of the overlay during a known-good user flow, store it as a regression baseline).

How to enable

Sign in at app.zenovay.com and open the Domains page.
Click the domain you want to debug.
Open Settings → Advanced, scroll to the Basic Settings section.
Toggle Allow Debug Overlay to ON.
On your own site, navigate to any URL with ?zenovay_debug=1 appended — for example https://your-site.com/?zenovay_debug=1 or https://your-site.com/checkout?zenovay_debug=1.

The overlay appears in the bottom-right corner about a second after the tracker loads.

Cache propagation: the tracker config is cached at the edge for up to 5 minutes after you flip the toggle. If the overlay doesn't appear immediately, hard-reload the page (Cmd/Ctrl + Shift + R) or wait a few minutes.

What you'll see

The overlay has three regions:

Header chips show the runtime state of the tracker on the current page:

cookieless ON | OFF — whether cookieless mode is active for this website. ON means the tracker is using window-scoped in-memory IDs and writing zero cookies. OFF means cookie-based session/visitor IDs are in use.
GPC ON | OFF — whether the visitor's browser sent a Global Privacy Control signal (Sec-GPC: 1 / navigator.globalPrivacyControl === true). When ON, behavioural enrichment (B2B, scoring) is skipped on the server.
consent: <state> — the last consent state the tracker observed (opt-in, opt-out, unknown). If you're using a consent management platform, this reflects the visitor's choice.
v<version> — the tracker script version currently running on the page.

Event list shows the most recent 20 outgoing events, newest first. Each row shows:

Wall-clock timestamp (HH:MM:SS, browser local time)
Event type
Up to 4 abbreviated property keys

Click any row to open the JSON modal.

JSON modal shows the full event JSON (after PII masking). Use the Copy JSON button to copy it to your clipboard — handy for sharing with a teammate or attaching to a support ticket.

Reading event types

Event type	What it means
`pageview`	A new page was viewed. Includes URL, referrer, UTM params, device class, screen size.
`heartbeat`	The visitor is still on the page. Fires every ~2 seconds while idle so we can compute time-on-page accurately.
`page_exit`	The visitor closed the tab or navigated away. Final delta for time-on-page.
`outbound_link`	A click on an `<a>` tag whose `href` points off your domain.
`goal_completion`	A configured goal fired. Includes the goal name and any custom parameters.
`funnel_step`	The visitor advanced to a step in a configured funnel.
`custom_event`	A `zenovay.track('event_name', {...})` call from your own code.
`error`	A JavaScript error captured by the tracker (only shipped if error tracking is enabled on your plan).
`core_web_vitals`	LCP / CLS / INP measurements for the current page (sent once per page once metrics stabilize).
`session_replay`	A chunk of session replay data was uploaded. The overlay shows only that the chunk shipped — never the recording contents.
`frustration_signal`	A rage-click, dead-click, or excessive scroll-jitter signal was detected.

PII masking

The overlay applies a display-side mask to every event before showing it on screen. The mask covers two cases:

Field name (key) match — any prop with one of these key names is replaced with [MASKED]:

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

Pattern match on the value — applied even if the key name doesn't match:

Strings matching the email shape ([email protected]) are partially redacted (a***@b***.tld).
Strings matching IPv4 (1.2.3.4) are replaced with [IP].
Strings longer than 80 characters that contain Mozilla|WebKit|Chrome|Safari|Firefox are truncated and labelled [UA truncated].

The masking happens only in the overlay's display layer. The raw event payload that the tracker actually sends to Zenovay is unchanged — that's what powers your dashboards. The mask only affects what you see on screen, so screenshots and copy-paste of JSON from the overlay are safe to share.

Privacy and compliance

The overlay is designed to be safe to enable in any environment, but you should still understand exactly what it does and doesn't do:

Zero cookies, zero localStorage. The event bus is a plain JavaScript array on window (window._zenovayDebugBus). It vanishes when the tab closes.
No remote logging. The overlay never makes a network call. Everything you see is rendered from data already in browser memory.
Lazy-loaded. The overlay UI is a separate HTTP resource (/debug-overlay.js) that only downloads when both gates are satisfied. Visitors without the URL parameter download zero overlay bytes.
The cookieless tracker invariant is preserved. If your website is on cookieless mode, enabling the overlay does not change the tracker's behavior — no cookies are written, the same window-scoped temporary IDs are used, and the cookieless chip in the header reads ON.
GPC is honored regardless. The overlay reads the GPC state from the tracker config but does not bypass it.

Troubleshooting

"I added ?zenovay_debug=1 and nothing happens."

Double-check the website setting is on. Both gates must be true.
Hard-reload the page (Cmd/Ctrl + Shift + R) — the tracker config is cached for up to 5 minutes after you flip the toggle.
Confirm your tracker version supports the overlay by opening devtools and running window.ZENOVAY_TRACKER_CONFIG — if allowDebugOverlay is false even though the toggle is on, the cache hasn't busted yet.
Check that no Content-Security-Policy on your site blocks scripts from api.zenovay.com.

"Overlay shows but no events appear."

Trigger an interaction on the page (click a link, scroll, navigate) to make the tracker fire something.
If you still see nothing, the tracker may not be sending — cross-reference Install Health which probes the same path from the server side.

"Overlay disappears on SPA route change."

The overlay should re-mount automatically across route changes. If it doesn't, it's a known edge case with frameworks that aggressively prune document.body children — please report a reproduction at help.zenovay.com.

"Multiple Zenovay trackers on my page."

Only one overlay mounts. The first tracker to initialize wins (window._zenovayDebugOverlayMounted guard).

"I see [MASKED] for fields I sent intentionally."

That's expected. The mask is applied unconditionally to a list of common PII key names. If you need to display a non-PII field with a sensitive-looking name (e.g. you used name for a non-personal label), rename the prop and re-test.

"The overlay covers an important part of my UI."

Click the × in the header to hide the overlay until the next page load.

When to disable

We recommend turning the Allow debug overlay toggle off on production once you've verified your install. While the double-gate prevents accidental exposure to ordinary visitors (who never appended ?zenovay_debug=1), keeping the website-side flag off as a default removes the second factor entirely and makes accidental exposure impossible — even if a developer mistakenly shares a debug URL.

Browser support

The overlay works on all evergreen browsers (Chrome, Firefox, Safari, Edge) and gracefully fails on older browsers without URLSearchParams or with restrictive CSP — it never throws an unhandled error in the host page.

Install Health — server-side probe of your tracker's recent activity.
Tracking script — full reference for the tracker snippet, including all data-* attributes.
Privacy compliance — cookieless mode, GPC handling, consent recording.