10 min de lecture

Troubleshooting

This guide covers common issues you might encounter when using Zenovay and how to resolve them.

Tracking Script Issues

Script Not Loading

Symptoms: No data appearing in your dashboard after installing the tracking script.

Possible Causes & Solutions:

1. Script Not Installed Correctly

Verify the script is in your page's <head> section:

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

Check that:

The script URL is correct
Your data-tracking-code matches your dashboard (Settings → Website)
The script loads before closing </head> tag

2. Content Security Policy (CSP) Blocking

If you have a CSP header, add Zenovay to your allowlist:

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

3. Ad Blocker or Privacy Extension

Some browser extensions may block analytics scripts. To verify:

Open DevTools (F12)
Check the Console tab for blocked requests
Test in an incognito window without extensions

Unlike traditional analytics, Zenovay is privacy-friendly and cookie-free, so it's less likely to be blocked by privacy tools.

Script Loads But No Data

Symptoms: Script loads successfully but dashboard shows no visitors.

Solutions:

Check Browser Console

Open DevTools Console and look for errors:

// You should see this if working correctly
[Zenovay] Tracking initialized for site: abc123
[Zenovay] Pageview tracked successfully

Verify Network Requests

Open DevTools → Network tab
Filter by "zenovay" or "api.zenovay.com"
Look for POST requests to /e/YOUR_TRACKING_CODE
Check if requests return 200 OK or error codes

Common Error Codes:

Status Code	Meaning	Solution
401	Invalid site ID	Double-check your `data-tracking-code`
403	Blocked by firewall	Check CSP headers or firewall rules
429	Rate limited	Too many requests, wait and retry
500	Server error	Contact support if persistent

Script Placement Issues

Zenovay automatically detects common installation mistakes and shows warnings in the browser console. You'll also see diagnostics in the dashboard when clicking Verify Installation.

Where to place the script:

Always place the Zenovay script in the <head> section of your HTML with the defer attribute:

Correct placementHTML

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

Common mistakes:

Mistake	Problem	Fix
Script in `<body>`	May miss first pageview, loads too late	Move to `<head>`
Script at end of `<body>`	Page fully loaded before tracker runs	Move to `<head>`
Missing `defer`	Blocks page rendering	Add `defer` attribute
Duplicate scripts	Inflates pageviews and metrics	Remove extra script tags
Wrong `data-id`	Events sent to wrong website	Copy code from Dashboard → Settings

Framework-specific guidance:

React: Use useEffect in your root App component, or add to public/index.html <head>
Next.js (App Router): Use <Script> component in app/layout.tsx with strategy="afterInteractive"
Next.js (Pages Router): Add in pages/_document.tsx inside <Head>
Vue: Add to public/index.html <head> section
WordPress: Use "Insert Headers and Footers" plugin → Scripts in Header
Shopify: Add to theme.liquid before </head>

First-party proxy issues:

If you're using a first-party proxy (e.g., /api/_z/script.js):

Verify the proxy URL returns a 200 response (not 404)
Check that the proxy forwards the X-Zenovay-Real-IP header
Try loading https://api.zenovay.com/z.js directly to isolate proxy vs. script issues
Ensure your server's Content-Security-Policy allows connections to api.zenovay.com

Console diagnostics:

When there are installation issues, you'll see messages like:

⚠️ [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

These warnings appear once per browser session and are designed to help you fix your setup.

Events Not Tracking

Symptoms: Page views work but custom events don't appear.

Check Event Syntax:

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

// Incorrect (missing event name)
window.zenovay('track',{
  button_name: 'signup'
});

Verify Script Loaded:

// Check if Zenovay is available
if (window.zenovay) {
  console.log('Zenovay loaded');
  window.zenovay('track', 'custom_event');
} else {
  console.error('Zenovay not loaded yet');
}

Use Ready Callback:

window.addEventListener('zenovay:ready', function() {
  // Zenovay is now ready
  window.zenovay('track', 'page_load_complete');
});

Dashboard Issues

Data Not Updating

Symptoms: Dashboard shows old data or doesn't update in real-time.

Solutions:

1. Clear Browser Cache

Press Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to hard refresh.

2. Check Date Range

Ensure the date range selector shows the correct period:

Click the date range dropdown
Select "Today" or "Last 24 hours"
Verify timezone is correct in Settings

3. Wait for Processing

Real-time data typically appears within 1-2 seconds, but:

Aggregated metrics may take 5-10 minutes
Historical reports update hourly

Zero Visitors Showing

Symptoms: Dashboard shows "0 visitors" despite traffic to your site.

Diagnostic Steps:

Verify Site ID: Settings → Website → Copy Site ID, compare with script
Check Filters: Remove any active filters (location, device, source)
Test Locally: Visit your site and check if you appear in real-time view
Review Exclusions: Settings → Privacy → Check if you've excluded your IP

By default, Zenovay excludes localhost and 127.0.0.1 from tracking to avoid counting development traffic.

Incorrect Visitor Numbers

Symptoms: Visitor counts don't match expectations or other analytics tools.

Common Reasons:

1. Definition Differences

Zenovay counts:

Unique Visitors: Based on anonymized visitor ID (24-hour window)
Visits: Separate sessions (30-minute timeout)
Pageviews: Each page load

Other tools may use different definitions or session timeouts.

2. Ad Blocker Impact

Some visitors use ad blockers that may:

Block traditional analytics but not Zenovay (privacy-friendly)
Block all analytics including Zenovay (aggressive settings)

3. Bot Filtering

Zenovay automatically filters known bots and crawlers. Other tools may:

Include bot traffic in counts
Use different bot detection methods

Integration Issues

WordPress Plugin Not Working

Symptoms: WordPress integration doesn't track visitors.

Solutions:

1. Verify Plugin Installation

Go to Plugins → Installed Plugins
Ensure "Zenovay Analytics" is activated
Check version is latest

2. Check Site ID Configuration

Go to Settings → Zenovay
Verify Site ID is entered correctly
Save changes and clear cache

3. Theme Compatibility

Some themes may conflict with header/footer injection:

// Add to your theme's functions.php as fallback
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 Conflicts

If using WP Super Cache, W3 Total Cache, or similar:

Clear all caches
Exclude Zenovay script from minification/combining
Test in incognito mode

React/SPA Not Tracking Route Changes

Symptoms: Only initial page load tracked, route changes not counted.

Solution: Implement client-side routing 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 />;
}

For 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 Issues

Authentication Failures

Symptoms: API requests return 401 Unauthorized.

Check API Key:

# Test your API key
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Common Mistakes:

Using site ID instead of API key
Missing X-API-Key header
API key expired or revoked
Wrong API key for environment (test vs production)

Generate New API Key:

Go to Settings → API Keys
Click "Create New Key"
Copy the key immediately (shown only once)
Replace old key in your application

Rate Limiting

Symptoms: API returns 429 Too Many Requests.

Check Rate Limit Headers:

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

Look for:

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

The X-RateLimit-Limit value reflects your plan's per-minute limit (e.g., 10 for Free, 30 for Pro, 60 for Scale, 120 for Enterprise).

Solutions:

Implement exponential backoff (see Rate Limits)
Cache API responses where possible
Batch requests instead of individual calls
Consider upgrading your plan for higher limits

Performance Issues

Script Slowing Down Page Load

Symptoms: Page load times increased after adding Zenovay.

Verify Async Loading:

Ensure the script has the async attribute:

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

Test Impact:

Use browser DevTools or Lighthouse:

Run Lighthouse audit with and without script
Compare "Time to Interactive" metrics
Check "Blocking Time"

Zenovay script is typically < 5KB gzipped and loads asynchronously, adding < 50ms to page load.

Dashboard Loading Slowly

Symptoms: Dashboard takes a long time to load charts and data.

Solutions:

1. Reduce Date Range

Loading 12 months of data is slower than 7 days:

Use shorter date ranges when possible
Apply filters to reduce data volume

2. Clear Browser Data

Clear browser cache and cookies
Disable browser extensions that may interfere
Try a different browser

3. Check Network

Test your internet connection speed
Try on a different network
Check if corporate firewall is throttling

Data Accuracy Issues

Missing Geographic Data

Symptoms: Some visitors show "Unknown" location.

Causes:

VPN or proxy usage by visitor
Privacy-focused browsers that mask location
Corporate networks with centralized IP addresses

This is expected behavior and affects 5-15% of visitors depending on your audience.

Referrer Shows as "Direct"

Symptoms: Most traffic shows as "Direct" instead of actual source.

Common Causes:

1. HTTPS → HTTP Transitions

Referrer is stripped when going from HTTPS to HTTP. Solution: Use HTTPS on your site.

2. Referrer Policy

Some sites use strict referrer policies:

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

This is the sending site's policy, not something you can control.

3. Mobile Apps and Email

Traffic from mobile apps and email clients often shows as direct - this is normal and expected.

Getting Help

If you're still experiencing issues after trying these solutions:

Check Service Status

Visit status.zenovay.com to see if there's a known outage or incident.

Collect Diagnostic Information

Before contacting support, gather:

Browser Console Logs:
- Open DevTools → Console
- Copy any error messages
- Take screenshot
Network Requests:
- Open DevTools → Network
- Filter by "zenovay"
- Screenshot failed requests with status codes
Site Information:
- Your site URL
- Site ID from dashboard
- Platform/CMS (WordPress, custom, etc.)
- Approximate traffic volume

Contact Support

Email: [email protected]

Include:

Detailed description of the issue
Steps you've already tried
Diagnostic information from above
Screenshots or screen recordings

Response Times:

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

Community Help

GitHub: github.com/zenovay
Documentation: Search our docs for specific topics
AI Assistant: Use the chat widget on any docs page

Troubleshooting

Tracking Script Issues

Script Not Loading

Script Loads But No Data

Script Placement Issues

Events Not Tracking

Dashboard Issues

Data Not Updating

Zero Visitors Showing

Incorrect Visitor Numbers

Integration Issues

WordPress Plugin Not Working

React/SPA Not Tracking Route Changes

API Issues

Authentication Failures

Rate Limiting

Performance Issues

Script Slowing Down Page Load

Dashboard Loading Slowly

Data Accuracy Issues

Missing Geographic Data

Referrer Shows as "Direct"

Getting Help

Check Service Status

Collect Diagnostic Information

Contact Support

Community Help

Additional Resources