Skip to content
Getting Started

Installation Guide

Install Invoker Analytics on any website, framework or website builder.

Basic Installation

Add the tracking script to your HTML, just before the closing </head> tag:

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

The script is also served from https://api.invoker.app/script.js. It's about 3.5 KB gzipped and loaded with defer, so it never blocks rendering.

Framework-Specific Installation

Static HTML / server-rendered sites

Paste the snippet into the <head> of every page (or your shared layout/template).

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My Website</title>
    <script
      defer
      src="https://cdn.invoker.app/script.js"
      data-site="YOUR_SITE_ID"
    ></script>
  </head>
  <body>
    ...
  </body>
</html>

Single Page Applications (SPAs)

By default the script records one pageview when the page loads. Client-side route changes are not tracked unless you enable SPA mode with the data-spa attribute:

  • data-spa="history" - tracks history.pushState navigations and back/forward (popstate). Use this for Next.js, React Router, Vue Router, SvelteKit, Angular, Remix, Gatsby, etc.
  • data-spa="hash" - tracks hashchange events and includes the hash in the page path (for #/route routers).
  • data-spa="auto" - uses history mode when the History API is available, otherwise hash mode.

Configuration Options

The tracking script is configured with data attributes on the <script> tag:

AttributeDefaultDescription
data-siteRequiredYour Site ID from site settings. Without it the script does nothing.
data-spaoffhistory, hash or auto. Tracks client-side route changes.
data-modeprivacyprivacy stores nothing on the visitor's device. enhanced keeps a visitor ID in localStorage for returning visitors; also switch the site to Enhanced in Site → Settings → Tracking mode. See Privacy & GDPR.
data-autotrueSend a pageview automatically on load. Set to false to track pageviews manually.
data-honor-dntfalseDon't send anything when the browser has Do Not Track enabled. (Can also be enforced server-side via site settings.)
data-canonicaltrueReport the URL from <link rel="canonical"> when present.
data-included-domainsallComma-separated hostnames; only track on these (alias: data-allowed-domains).
data-excluded-domainsnoneComma-separated hostnames to never track on (e.g. localhost,staging.example.com).
data-outbound-linkstrueAutomatically track clicks on external links as outbound_link events.
data-file-downloadstrueAutomatically track file download clicks as file_download events.
data-download-extensionspdf, zip, docx, csv, mp4, dmg, …Comma-separated file extensions treated as downloads.
data-404-errorstrueDetect 404 pages (title containing "404"/"not found", or <meta name="invoker-status" content="404">) and record a 404_error event.
data-trackerhttps://api.invoker.appCustom collection endpoint base URL (the script appends /ping). Only needed if we gave you a dedicated endpoint.

See Tracking Script for examples and JavaScript SDK for the window.invoker API (custom events, goals and revenue).

Verifying Installation

  1. Open your website in a browser where you haven't opted out with blockTrackingForMe() and whose IP isn't blocked in site settings
  2. Open Developer Tools (F12) and go to the Network tab
  3. Reload the page and check that script.js loads from cdn.invoker.app with status 200
  4. Look for a request to https://api.invoker.app/ping?... - that's the pageview
  5. In the console, window.invoker.isTrackingEnabled() should return true
  6. Open the Realtime view in your Invoker dashboard - the visit should appear within about a minute

Troubleshooting

Script not loading

  • Make sure the tag is in the <head> (or rendered by your framework's script component)
  • Check for a Content Security Policy blocking cdn.invoker.app (see below)
  • Ad/tracker blockers may block the script - test with them disabled

Pageviews not appearing

  • Check the browser console for [Invoker] Missing site id or Invalid site id format warnings - the data-site value must exactly match the Site ID in your site settings
  • If you set Included Domains in site settings (or data-included-domains), the hostname you're testing on must be listed. *.example.com matches subdomains but not example.com itself
  • Make sure tracking is enabled for the site and your IP or country isn't blocked
  • Make sure you haven't opted this browser out with window.invoker.blockTrackingForMe()
  • Check your monthly pageview allowance on the Usage page - hits over the limit aren't recorded
  • For SPAs, make sure data-spa is set if pageviews only show for the first page

Content Security Policy (CSP)

Pageviews are sent as an image beacon and events/goals with navigator.sendBeacon, so a strict CSP needs:

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