Staats
Tracking
A ~1.5KB tracker for automated pageviews and declarative custom events.
Pageviews
The script tag records a pageview on initial load and listens to client-side single-page app routing.
It hooks into pushState, replaceState, and popstate, so
framework navigation (Next.js, Vite, React, Vue, Svelte) is measured automatically without extra configuration.
<script defer data-site="YOUR_SITE_CODE" src="https://www.staats.ai/s.js"></script>Custom events
Add a data-track attribute to any clickable HTML element. No site-side JavaScript needed:
the tracker uses a single delegated event listener to capture interactions dynamically:
<button data-track="signup_click">Start free trial</button>
<a href="/download" data-track="download_click">Download App</a>For non-click interactions or programmatic flows, call window.track:
window.track('checkout_completed')When your coding agent instruments an event, have it record what the event means in site context
(update_site_context with the events map) so any future agent session can
look up event definitions instantly without re-parsing your source code.
Event naming conventions
Use clean, lowercase snake_case names that follow a target_action pattern:
pricing_click, trial_started, export_csv_click. Event names are
capped at 120 characters. Consistent naming ensures your agent can query and build funnels over them reliably.
What each event records
| Field | Description |
|---|---|
| type & name | pageview, or custom with the event name |
| path | Page pathname (clean URLs without query strings) |
| referrer domain | External referral hostnames only (internal hops filtered) |
| utm parameters | Campaign attribution (utm_source, utm_medium, utm_campaign) |
| device & browser | Derived from User-Agent: desktop / mobile / tablet |
| country | Inferred via client timezone (no IP geolocation services; see Data & Privacy) |
| visitor | Pseudonymous hash rotating daily (zero cookies, zero persistent storage) |
Known search engine crawlers and automated bots are filtered out at ingestion and never count toward your event quota.
Excluding your own visits
Your own browsing counts the same as anyone else's. On a quiet site that can be most of the traffic, and it is enough to trigger a false anomaly. Run this once in the browser console, on the site you want to skip:
localStorage.staats_ignore = 'true'The flag is stored per browser and per domain, so repeat it in every browser you use and on each
site you own. To start counting yourself again, run
localStorage.removeItem('staats_ignore').
Local development is already excluded. Pages opened from file:// and any host on
localhost are never recorded, so your dev server stays out of production numbers with
no setup.
Leave the script off your 404 page
If your 404 page carries the script tag, every mistyped URL and every crawler probe is recorded as a pageview for a page that does not exist, and those paths then sit in your stats looking like real ones. Serve your 404 page without the snippet.