Skip to Content
UsageMapDocs
Website analytics

Add the tracker

One script tag, or the npm package. How the tracker works, which profile to choose, and what to allow in your Content Security Policy.

The UsageMap tracker is a small script (about 3 KB gzipped) with no dependencies. It records a page view on load and on every route change, and sends nothing else unless you call track().

Install

Copy the tag from your website's Snippet tab in the app and paste it into the <head> of every page:

<script
  src="https://e1.usagemap.dev/lib/1.1.0/standard.js"
  integrity="sha384-AYjFWyBUxxvOL92oDDKxAus7EAPjONT2RDrOiuPh4XUiEJNKkMaZqGVBDw4Lqn0+"
  crossorigin="anonymous"
  data-site="YOUR_SITE_KEY"
  defer
></script>
AttributeWhat it does
srcA fixed version of the tracker. Files never change once published, and there is no latest URL.
integrityThe file's hash. The browser refuses a file that doesn't match, so nobody can swap the code under you.
data-siteYour site key (22 characters), from the app.
data-consent="required"Optional. Send nothing until you call grantConsent(). See consent mode.

Profiles

Each website uses one of two tracker profiles, chosen when you add the website.

standard (default)strict
Filestandard.jsstrict.js
Page path✓✓
Referrer host (not the full URL)✓—
Screen size class (S, M, L, XL)✓—
Language (for example en)✓—
Wallets Kit detected✓—

Use strict when you want the smallest possible footprint: it sends the page path and nothing else.

Content Security Policy

If your site sets a Content Security Policy, allow the tracker host for scripts and both ingest hosts for requests:

script-src  https://e1.usagemap.dev;
connect-src https://e1.usagemap.dev https://e2.usagemap.dev;

The tracker sends to two independent hosts and switches automatically if one is unreachable.

Don't proxy the tracker

Serving the tracker or its requests through your own server makes every visit look like it comes from one machine, and all of them are then counted as suspect.

What happens on each page view

The page loads (or the route changes) and the tracker sees a new path.
It asks UsageMap for a small challenge and solves a light proof of work in the background, which makes fake traffic expensive.
It sends the path only: never the query string, the #fragment or the page title.
UsageMap checks the event and counts it as verified, suspect or rejected. You see all three in the dashboard.

Nothing at all is sent, not even the challenge, when the visitor has Global Privacy Control or Do Not Track turned on, has opted out, or hasn't given consent in consent mode.

On this page