Skip to content
Developers

Tracking Script Configuration

Advanced configuration options for the Invoker Analytics tracking script.

The Script

There is a single script, https://cdn.invoker.app/script.js (also served from https://api.invoker.app/script.js). It's about 3.5 KB gzipped and includes pageviews, custom events, goals, revenue, SPA support, outbound-link, file-download and 404 tracking. Every feature is configured with data-* attributes on the script tag.

<script
  defer
  src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
></script>

data-site is the only required attribute: your site's 8-character Site ID from Site → Settings. The full list of attributes and defaults is in the Installation guide.

SPA Mode

Single-page apps change routes without a page load. Enable SPA mode so each navigation is recorded:

<!-- pushState / popstate routers (Next.js, React Router, Vue Router, SvelteKit, ...) -->
<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-spa="history"></script>

<!-- Hash routers (#/route) -->
<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-spa="hash"></script>
  • history - wraps history.pushState and listens for popstate (back/forward)
  • hash - listens for hashchange and includes the hash in the tracked path
  • auto - history mode when the History API exists, otherwise hash mode

replaceState calls are not counted as new pageviews.

Domain Filtering

Only track on your production hostnames, or skip specific ones such as local development and staging:

<!-- Only track on these hostnames -->
<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-included-domains="example.com,www.example.com"></script>

<!-- Never track on these hostnames -->
<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-excluded-domains="localhost,staging.example.com"></script>

These attributes match the exact window.location.hostname. You can also enforce allowed and excluded domains server-side in Site → Settings → Included / Excluded Domains, which supports wildcards like *.example.com.

Manual Pageviews

Disable the automatic pageview and send pageviews yourself (for example, after a consent check or once your router has resolved the final URL):

<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-auto="false"></script>

<script>
  // later, when you're ready
  window.invoker.trackPageview()
  // or with overrides
  window.invoker.trackPageview({ url: '/virtual/step-2', title: 'Checkout step 2' })
</script>

Tracking Mode

By default the script runs in Privacy mode and stores nothing on the visitor's device. To recognise returning visitors across days, switch the site to Enhanced in Site → Settings → Tracking mode and add data-mode="enhanced":

<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-mode="enhanced"></script>

data-mode accepts privacy (default) or enhanced. Enhanced mode needs visitor consent in the EU/UK, so load the script only after consent there. See Privacy & GDPR.

Do Not Track

<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-honor-dnt="true"></script>

With data-honor-dnt="true", nothing is sent from browsers with Do Not Track enabled. You can also turn on Respect Do Not Track in site settings to drop those hits on the server.

Automatic Event Tracking

Outbound links, file downloads and 404 pages are tracked automatically as the outbound_link, file_download and 404_error events. Turn any of them off, or change which file types count as downloads:

<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-outbound-links="false"
  data-file-downloads="true"
  data-download-extensions="pdf,zip,dmg"
  data-404-errors="true"></script>

404 detection looks for "404" or "not found" in the page title. For a reliable signal, add <meta name="invoker-status" content="404"> to your 404 page, or call window.invoker.track404() from your SPA's not-found route.

Canonical URLs

By default, if the page has a <link rel="canonical">, its URL is reported instead of the current URL, so duplicate URLs are grouped together. Set data-canonical="false" to always use the real URL.

Custom Tracker Endpoint

Hits are sent to https://api.invoker.app/ping. If you were given a dedicated endpoint, point the script at it with data-tracker (the script appends /ping):

<script defer src="https://cdn.invoker.app/script.js"
  data-site="YOUR_SITE_ID"
  data-tracker="https://collect.example.com"></script>

Opting Yourself Out

Your own visits are counted like any other visitor's. To stop counting a browser, run this in the console on your site (or block your IP address in site settings - see Traffic filtering):

window.invoker.blockTrackingForMe()   // opt out (stored in localStorage)
window.invoker.enableTrackingForMe()  // opt back in

What the Script Stores

In Privacy mode (the default) the script stores nothing: no cookies, no localStorage, no sessionStorage and no fingerprinting. It removes the invoker_cid and invoker_session keys left by older script versions. Visitors and sessions are worked out on the server with a hash that rotates every day. The only thing it may store is the opt-out flag above, when a visitor asks for it.

In Enhanced mode the script stores a random visitor ID (invoker_cid) and a session ID with a 30-minute inactivity timeout (invoker_session) in localStorage. When storage is blocked it falls back to the Privacy mode daily hash. If the script is served through a first-party proxy on your domain, the API may also set first-party inv_visitor/inv_sid cookies. There are no third-party cookies, no ads and no cross-site tracking in either mode. See our Cookie Policy and Privacy Policy.

Content Security Policy

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

Pageviews are sent as an image beacon (img-src), events and goals with navigator.sendBeacon (connect-src).

Testing Your Installation

  1. Open your site in a browser that hasn't opted out and whose IP isn't blocked in site settings
  2. Open developer tools (F12) and go to the Network tab
  3. Reload and look for a request to api.invoker.app/ping?sid=YOUR_SITE_ID… - it returns a 1×1 pixel
  4. Run window.invoker.isTrackingEnabled() in the console - it should return true

The visit should appear in the Realtime view of your dashboard within about a minute.

Troubleshooting

Script not loading?
  • Check the URL is https://cdn.invoker.app/script.js
  • Verify no ad blocker or CSP is blocking the request
  • Check the browser console for errors
No data appearing?
  • Check data-site matches the Site ID in your site settings (look for [Invoker] console warnings)
  • Check the hostname is allowed by Included Domains in site settings and data-included-domains
  • Make sure you haven't opted out with blockTrackingForMe() and your IP or country isn't blocked
  • Check you haven't reached your monthly pageview limit (see the Usage page)
Duplicate pageviews?
  • Check you haven't added the script twice (e.g. in a layout and via a tag manager)
  • If using data-spa, don't also call trackPageview() on route changes