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
| Environment | URL |
|---|---|
| Production CDN | https://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
| Attribute | Required | Description |
|---|---|---|
src | Yes | Points to latest.js on the CDN |
defer | Recommended | Non-blocking load |
data-collect-dnt="true" | No | When present, measure visitors with Do Not Track enabled |
HTTP endpoints
| Method | Path | When |
|---|---|---|
POST | /ping | Page view / visit start |
POST | /exit | Visit 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"
}
}
| Field | Notes |
|---|---|
visitId | Generated in the browser per visit; not stored in cookies |
url | Full page URL; hostname must match a registered site |
visibleSeconds | Seconds the document was in the visible state |
browser.timezone | IANA name; used for country inference on the server |
Visit lifecycle
- Load — script runs (unless blocked by Do Not Track and
data-collect-dntis absent). - Ping — initial
/pingwithvisibleSecondsusually0or small. - Visibility — timer runs only while
document.visibilityState === 'visible'. - Exit —
/exitonpagehide, 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:
- Send
/exitfor the current visit. - Generate a new
visitId, reset timers, updatepageUrltowindow.location.href. - Send
/pingfor 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:
- Site lookup — hostname from
urlmust match a site on your team. - Origin / Referer — when the browser sends
OriginorReferer, the host must match the host inurl(prevents arbitrary cross-site injection). - Exclusions — path regex and IP/CIDR rules on the site may discard the hit.
- 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.