Tracker Script#
The Antics collection tracker is a dependency-free JavaScript file that runs in the browser. It collects pageviews, custom events, scroll depth, attention evidence, and Core Web Vitals. The tracker sets no cookies and does not access localStorage or sessionStorage.
How It Works#
On page load, sends a
POST /api/eventwith the page URL, referrer, and viewport widthOn page navigation (SPA), intercepts
pushState/replaceStateand sends another eventOn page exit (
pagehide), sends time spent on the page and max scroll depth, including the first screen when the reader never scrolledCore Web Vitals (LCP, INP, CLS) are measured via
PerformanceObserverand sent onpagehide, including the samektracker token as the pageview
Privacy#
Daily pseudonymous visitor bucket: the server computes a daily id from a random salt, the registered site, a coarse browser family, and a masked address (an IPv4 /24 or an IPv6 /48). This groups same-day events; it is not a cryptographic identifier or an anonymity boundary. The public calendar date is not the salt. The UTC day that contains the first start of this scheme keeps the previous inputs.
When the salt changes: at UTC midnight. The salt for the current UTC day is stored on disk beside the data directory, outside the backup of the live stores, and loaded again when the process restarts. A restart on that day keeps the same bucket, so a visitor seen before and after a restart is counted once. The new day gets new bytes and every other day file is removed, so the same address cannot remake yesterday’s bucket. Grouping holds for that UTC day and no longer. It is never an identifier that outlives the day.
No raw IP in analytics events: the source IP is used for GeoIP lookup and visitor-bucket derivation. The raw IP address is not stored in analytics events.
No collection cookies or browser storage: the tracker sets no cookies and does not access localStorage or sessionStorage.
No active device probing: the tracker does not use canvas, font, or WebGL probing. It does collect viewport width, performance entries, and interaction counts described in the tracker reference.
Payload Format#
Each event is a JSON POST to /api/event:
{
"n": null, // event name (null = pageview)
"u": "https://...", // page URL
"r": "https://...", // referrer
"w": 1920, // viewport width
"k": "...", // optional site-scoped tracker token
"t": 5, // seconds on previous page
"p": {} // custom event properties
}
Script Attributes#
<script defer src="https://your-antics-instance/antics.js"
data-api="https://your-antics-instance/api/event">
</script>
data-token: route this install to a registered path or bind it to a revocable site token. Host installs can omit it.data-api: override the event collection endpoint (default: same origin as the script)
For path-scoped sites, register the full prefix (host/path) and keep data-token in the snippet. Browser referrer policy can strip the path from cross-origin requests, so the token-bound route is the supported install path for GitHub Pages project docs, Sphinx subdirectories, and similar static publishing setups. Tokenless events on the same host continue to report to the host site.
Outbound Link Tracking#
If you want to track clicks on external links, add this after the tracker:
<script>
document.addEventListener('click', function(e) {
var a = e.target.closest('a');
if (a && a.hostname !== location.hostname)
antics.event('Outbound Link', { url: a.href });
});
</script>
Content Blockers and Server Logs#
Some content blockers prevent third-party analytics scripts from loading. Antics supports two alternatives when this affects coverage:
Self-host the script: serve
antics.jsfrom your own domain (e.g.,/js/a.js) so ad blockers don’t recognize itCaddy log ingestion: enable
ANTICS_LOG_PATHon TurtleTech-managed infrastructure or a compatible gateway to ingest eligible server requests
Server-log events provide request coverage rather than browser interaction signals. Apply the same disclosed privacy and retention policy to the source logs.
Objection#
The tracker sends nothing when navigator.globalPrivacyControl is true or when window.__anticsOptOut is true. Put this script before antics.js to set the flag, and set it to false to clear it. The flag is not a cookie:
<script>
window.__anticsOptOut = true;
</script>
The collector also honours Sec-GPC: 1 and DNT: 1 with the same 202 it uses for any accepted event, and it does not store that event. The objection counter and both settings are described in the tracker reference and on the objection page.