Get started
Install the tracker
usage.io measures traffic with one deferred JavaScript file. The script does not set cookies or use localStorage. It sends events to usage.io with fetch, credentials: omit, and JSON bodies.
Always use the snippet shown in the app for your site so options such as Collect Do Not Track traffic are correct.
Where to get your snippet
- Open the site in the dashboard.
- Go to Settings.
- Open the Tracking Script section.
- Copy the full
<script>tag.
In production the script URL is typically:
<script src="https://cdn.usage.io/latest.js" defer></script>
If your site collects Do Not Track visitors, the tag includes data-collect-dnt="true".
Where to place the tag
Paste the snippet before the closing </body> tag on every page template or layout that should be counted.
- Multi-page sites — add it to the shared footer or base layout once.
- Single-page apps (React, Vue, Svelte, Next.js, etc.) — add it to the root HTML shell or document layout once. The script hooks the History API so in-app navigations count as separate page views without pasting the tag on every route.
- WordPress and other CMS platforms — use a theme footer hook, child theme
footer.php, or a header/footer injection plugin.
Deploy the change to your production host (or staging, if that host matches a domain you registered in usage.io).
Use the dashboard snippet
Do not hand-edit the script URL unless you are following explicit guidance from support. The snippet in Settings is the source of truth for your site.
What happens when a page loads
When the script runs on a allowed visitor (see Do Not Track below):
- It generates a random visit ID for that page view session on the client. This ID is not stored in cookies.
- It sends POST /ping with the page URL, visible-time counter, and coarse browser metadata (User-Agent, language, screen and viewport size, timezone, and whether cookies are enabled in the browser).
- While the tab is visible, it accumulates visible seconds (time in the foreground).
- When the visitor leaves the tab or navigates away (including SPA route changes), it sends POST /exit with the final visible time.
For SPA navigations, the script ends the current visit and starts a new one so each route change is tracked as its own page view.
Do Not Track
By default, if the visitor’s browser reports Do Not Track, the script does not run and no data is sent. You can change this per site with Collect Do Not Track traffic in site settings, which adds data-collect-dnt="true" to the snippet. Only enable this if it matches your privacy disclosures and applicable law.
Content Security Policy (CSP)
If your site sends a Content-Security-Policy header, allow:
| Directive | Host |
|---|---|
script-src | https://cdn.usage.io |
connect-src | https://usage.io |
The tracker posts to /ping and /exit on the usage.io API host.
Platform checklist
| Check | Action |
|---|---|
| Snippet on all public layouts | One copy in the shared template |
| Correct domain in usage.io | Hostname on the page must match your registered site |
| Ad blockers | Can block analytics hosts during testing |
| CSP | Script and connect hosts allowed |
Next steps
- Verify tracking after deployment
- Tracker reference for payload and SPA details
- Privacy and data for what fields are sent