Localhost Testing

By default, Zenovay blocks tracking on localhost and other local environments to prevent test data from polluting your analytics. You can enable local tracking for development and testing.

Enable Localhost Tracking

Option 1: Dashboard Toggle (Recommended)

1. Go to your Zenovay Dashboard
2. Open Domains and click your site
3. In the domain settings, open the Advanced section
4. Enable the "Allow Localhost" toggle
5. Click save

Option 2: Script Attribute

If you prefer to control this per-environment via your HTML, add data-allow-localhost="true" to the script tag:

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

Note: the dashboard setting above is the effective control. The server only accepts localhost events when it is enabled, and the tracker's settings fetch takes precedence over this attribute. Keep the attribute for offline development (when the settings fetch cannot complete); it has no effect on production domains.

Option 3: Dynamic Script Loading

For frameworks like React or Next.js where you load the script dynamically:

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

How It Works

Zenovay's tracker detects local environments by checking the hostname:

When a local environment is detected, the tracker checks two things (in order):

1. Server settings — The tracker fetches your website's configuration from the Zenovay API. If allow_localhost is enabled in the dashboard, tracking proceeds.
2. Script attribute — If the API call fails or hasn't completed, the data-allow-localhost="true" attribute on the script tag acts as a fallback.

If neither is set, tracking is blocked and you'll see this message in the browser console:

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

Verifying It Works

Browser Console

Open DevTools (F12) → Console tab. With localhost tracking enabled, you should see:

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

If localhost is blocked, you'll see:

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

Network Tab

Open DevTools → Network tab and filter by zenovay or api.zenovay.com:

1. GET z.js — Script loads (200 OK)
2. GET /api/websites/settings/ZV_... — Settings fetch (200 OK, response includes allow_localhost: true)
3. POST /e/ZV_... — Pageview event tracked (200 OK)

If step 3 returns 403, your domain verification is blocking the request. Make sure allow_localhost is enabled in your dashboard settings.

Dashboard

After a page load on localhost, go to your Zenovay dashboard. Open Domains, select your site, and open the Analytics tab. Under the Hosts breakdown, you should see localhost (or 127.0.0.1) listed as a source.

Debug Mode vs Allow Localhost

These are two separate settings with different purposes:

You can enable both during development for maximum visibility, but they work independently.

• Allow Localhost only controls whether tracking runs on localhost
• Debug Mode only controls whether debug output appears in the console

Using with the Load Endpoint

If you use the /load endpoint (recommended for production), localhost settings are automatically injected by the server:

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

With the /load endpoint, you only need to enable "Allow Localhost" in the dashboard — no data-allow-localhost attribute required.

First-Party Proxy on Localhost

If your production setup uses a first-party proxy (e.g., /api/_z/script.js), the proxy typically won't work on localhost since it's a server-side route that forwards to api.zenovay.com.

Solutions:

1. Use the direct script on localhost: Switch to https://api.zenovay.com/z.js in development
2. Set up a local proxy: Configure your dev server to proxy /api/_z/ to https://api.zenovay.com/
3. Use environment-based script URL: Load from your proxy in production, direct in development

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

Troubleshooting

Tracking not working on localhost

1. Check the dashboard setting: Open Domains, select your site, open the Advanced section and verify "Allow Localhost" is enabled
2. Hard refresh: Changes take up to 30 seconds. Do Ctrl+Shift+R to clear cached scripts
3. Check the console: Open DevTools and look for [Zenovay] messages
4. Verify the script loads: Check Network tab for z.js returning 200
5. Check for ad blockers: Browser extensions may block analytics even on localhost

Events return 403

The API rejected your tracking request due to domain verification. This means:

• allow_localhost is not enabled in your website settings, OR
• The setting hasn't propagated yet (wait 30 seconds and retry)

Events fire but data doesn't appear in dashboard

Localhost data appears in your analytics alongside production data. Check:

• Hosts tab in Analytics — look for localhost entries
• Filters — make sure you're not filtering out localhost traffic
• Time range — ensure you're looking at today's data