Skip to content
Support

Troubleshooting Guide

Common issues and solutions to get your analytics working correctly.

Analytics Not Tracking

If your dashboard shows no data, work through these checks in order:

Step 1: Verify the snippet and Site ID
  1. 1. Open your live site, right-click and choose "View Page Source"
  2. 2. Search for cdn.invoker.app/script.js — it should be inside <head>
  3. 3. Compare the data-site value with the Site ID shown under Site → Settings in your dashboard. It must match exactly (8 characters, case-sensitive). If you regenerated the Site ID, update the snippet.
<script defer src="https://cdn.invoker.app/script.js" data-site="YOUR_SITE_ID"></script>
Step 2: Check the browser developer tools
  • Network tab: reload the page. cdn.invoker.app/script.js should load with status 200, followed by a request to api.invoker.app/ping. If the script loads but no /ping request appears, tracking was skipped (see the checks below).
  • Console tab: look for messages starting with [Invoker]:
    • Missing site id (data-site / site). Tracking disabled. — the attribute is missing or was stripped by your CMS/framework
    • Invalid site id format. — the value isn't 6–12 letters/digits (e.g. you pasted your domain)
  • Quick check: run window.invoker?.isTrackingEnabled() in the console. false means the script decided not to track this browser.
Step 3: Common causes

Monthly limit reached

Pageviews and events over your plan's monthly allowance are not recorded until usage resets or you upgrade. Check the Usage page. When a 14-day trial ends, the Free plan's limits apply.

Tracking turned off

In Site → Settings → Privacy & Tracking, make sure Enable Tracking is on.

Local opt-out

If invoker.blockTrackingForMe() was called in this browser, a blockInvokerTracking key is stored in localStorage. Run invoker.enableTrackingForMe() or remove the key.

Site settings: allowed domains, blocked IPs and countries

In Site → Settings, check that the hostname you're testing on is in the allowed domains list (if one is set) and not in the excluded domains, and that your IP address or country isn't blocked. Bot filtering also drops known crawlers and headless browsers (detected from the user agent).

Script domain filters

data-included-domains only tracks listed hostnames and data-excluded-domains skips listed hostnames. Hostnames must match exactly — www.example.com and example.com are different entries.

Do Not Track

With data-honor-dnt="true" on the script, or "Respect Do Not Track" enabled in site settings, browsers sending DNT are not counted. Both are off by default.

Ad blockers and privacy extensions

Some blockers block analytics scripts regardless of how privacy-friendly they are. Disable the extension for your site while testing.

Single-page apps only record the first page

Client-side navigation is not tracked automatically. Add data-spa="history" (pushState routers such as Next.js, React Router, Vue Router, SvelteKit), data-spa="hash" (hash routing) or data-spa="auto".

Caching

If you just added the snippet, purge your page cache / CDN cache so visitors receive the updated HTML.

Content Security Policy (CSP)

If your site sends a Content-Security-Policy header, allow the script host and the API. Pageviews are sent as a tiny <img> beacon and events/goals use navigator.sendBeacon, so the API needs both img-src and connect-src:

script-src  'self' https://cdn.invoker.app;
img-src     'self' https://api.invoker.app;
connect-src 'self' https://api.invoker.app;

If you set a custom endpoint with data-tracker, allow that host instead of api.invoker.app.

Custom Events Not Recording

If pageviews work but custom events aren't showing up:

  • Wait for the script: the snippet uses defer, so window.invoker doesn't exist until the script has run. Call it from event handlers (clicks, submits) or after page load, and use optional chaining.
  • Use the right method: window.invoker.trackEvent(name, payload) for events, trackGoal(code, cents) for goals and trackRevenue({amount}) for revenue. See the JavaScript SDK reference.
  • Check the Network tab: each event triggers a request to api.invoker.app/ping.
// Correct event tracking
document.querySelector('#signup')?.addEventListener('click', () => {
  window.invoker?.trackEvent('button_click', {
    variant: 'primary',
    location: 'header'
  })
})

Real-time Data Delayed

Hits are written in small batches every few seconds, and the Realtime view refreshes every 30 seconds. Other reports may take a little longer to update. If you don't see a visit straight away, wait a minute and reload.

Visitor Counts Differ From Other Tools

  • Bot filtering: Invoker filters known bots and crawlers, which other tools may count.
  • Visitor identification: in Privacy mode (the default) visitors are recognised for one day with a server-side hash of IP address and user agent, so someone visiting on several days counts once per day in a multi-day range. People sharing an IP and browser (an office, mobile carrier NAT) can be merged, and a phone switching networks can be counted twice. Enhanced mode keeps a random ID in localStorage instead and counts returning visitors across days (see Privacy & GDPR).
  • Blockers and DNT: visitors blocking the script, or sending DNT when you honour it, are not counted.
  • Your own visits: they are counted unless you block your IP or opt out with blockTrackingForMe() (see Traffic filtering).
  • Monthly limits: hits over your plan's allowance aren't recorded.

Session Duration Shows Zero

  • Single-page visits: duration is measured between hits in a session, so a visit with one pageview and no events has a duration of 0.
  • Inactivity: sessions end after 30 minutes without activity.
  • SPAs: without data-spa, route changes aren't recorded, so most sessions look like single-page visits.

Missing or Wrong Geographic Data

Locations are looked up from the visitor's IP address using a local DB-IP database (no third-party lookup service). Results can be inaccurate or missing for:

  • VPN, proxy or iCloud Private Relay users
  • Corporate networks with central exit points
  • Mobile carriers that route traffic through distant gateways

Cannot Access Dashboard

Forgot password

Use the "Forgot password" link on the sign-in page to receive a reset link by email. Check your spam folder if it doesn't arrive within a few minutes.

API Errors

Common API error codes and solutions:

401 Unauthorized
Missing, invalid or revoked bearer token
Check that you send a valid token as Authorization: Bearer <token>. See the API reference for how to create one.
403 Forbidden
You don't have permission to access this resource
Check that your account owns the site or is a team member with a sufficient role.
422 Unprocessable Content
Validation failed
The response body lists the invalid fields under errors.
429 Too Many Requests
Rate limit exceeded
Wait before retrying and use exponential backoff. Rate limits are listed in the API reference.
500 Internal Server Error
Something went wrong on our end
Try again later. If the issue persists, contact support.

Still Need Help?