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:
- 1. Open your live site, right-click and choose "View Page Source"
- 2. Search for
cdn.invoker.app/script.js— it should be inside<head> - 3. Compare the
data-sitevalue 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>
- Network tab: reload the page.
cdn.invoker.app/script.jsshould load with status 200, followed by a request toapi.invoker.app/ping. If the script loads but no/pingrequest 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/frameworkInvalid 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.falsemeans the script decided not to track this browser.
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, sowindow.invokerdoesn'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 andtrackRevenue({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:
Authorization: Bearer <token>. See the API reference for how to create one.errors.Still Need Help?
Contact Support
[Invoker] console messages.