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

  1. Open the site in the dashboard.
  2. Go to Settings.
  3. Open the Tracking Script section.
  4. 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):

  1. It generates a random visit ID for that page view session on the client. This ID is not stored in cookies.
  2. 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).
  3. While the tab is visible, it accumulates visible seconds (time in the foreground).
  4. 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:

DirectiveHost
script-srchttps://cdn.usage.io
connect-srchttps://usage.io

The tracker posts to /ping and /exit on the usage.io API host.


Platform checklist

CheckAction
Snippet on all public layoutsOne copy in the shared template
Correct domain in usage.ioHostname on the page must match your registered site
Ad blockersCan block analytics hosts during testing
CSPScript and connect hosts allowed

Next steps

Previous
Add your website