Developers

Tracker reference

This reference describes the production tracker script (latest.js) and how usage.io accepts events. For installation steps, see Install the tracker.


Script URL

EnvironmentURL
Production CDNhttps://cdn.usage.io/latest.js

The app shows the exact tag to use, including optional data-collect-dnt="true", under Settings → Tracking Script.


Script attributes

AttributeRequiredDescription
srcYesPoints to latest.js on the CDN
deferRecommendedNon-blocking load
data-collect-dnt="true"NoWhen present, measure visitors with Do Not Track enabled

HTTP endpoints

MethodPathWhen
POST/pingPage view / visit start
POST/exitVisit end, includes final visibleSeconds

Requests are sent to the usage.io API origin (cross-origin from your site). Headers include Content-Type: application/json. The script uses credentials: omit and CORS.


JSON payload

Both /ping and /exit send an object with this shape:

{
  "visitId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://example.com/blog/post",
  "visibleSeconds": 42,
  "browser": {
    "userAgent": "Mozilla/5.0 ...",
    "language": "en-US",
    "cookieEnabled": true,
    "screenWidth": 1920,
    "screenHeight": 1080,
    "viewportWidth": 1200,
    "viewportHeight": 800,
    "timezone": "America/New_York"
  }
}
FieldNotes
visitIdGenerated in the browser per visit; not stored in cookies
urlFull page URL; hostname must match a registered site
visibleSecondsSeconds the document was in the visible state
browser.timezoneIANA name; used for country inference on the server

Visit lifecycle

  1. Load — script runs (unless blocked by Do Not Track and data-collect-dnt is absent).
  2. Ping — initial /ping with visibleSeconds usually 0 or small.
  3. Visibility — timer runs only while document.visibilityState === 'visible'.
  4. Exit — /exit on pagehide, before SPA navigation, or when replacing the visit.

exit is sent at most once per visit ID unless a new visit starts.


Single-page applications

The script wraps history.pushState and history.replaceState and listens for popstate. On each navigation:

  1. Send /exit for the current visit.
  2. Generate a new visitId, reset timers, update pageUrl to window.location.href.
  3. Send /ping for the new URL.

You do not need to call a JavaScript API manually for route changes.


Do Not Track

If navigator.doNotTrack (or equivalent) indicates DNT is enabled and data-collect-dnt="true" is not set on the script element, the script returns immediately and sends nothing.


Server-side checks

Before a page view is stored and aggregated:

  1. Site lookup — hostname from url must match a site on your team.
  2. Origin / Referer — when the browser sends Origin or Referer, the host must match the host in url (prevents arbitrary cross-site injection).
  3. Exclusions — path regex and IP/CIDR rules on the site may discard the hit.
  4. Subscription — inactive billing may affect whether data appears in analytics.

Pseudonymization of the client IP and User-Agent parsing happen on the server. See Privacy and data.


Content Security Policy

Allow script loads from https://cdn.usage.io and connect (XHR/fetch) to https://usage.io for /ping and /exit.

If your security policy uses nonces or hashes, ensure the tracker script and API host are permitted according to your CSP rules.


Previous
FAQ