Tracking
Tracker API
Every data-attribute and JavaScript command of the tracker, and what it collects automatically.
The tracker is configured with data-* attributes on its script tag and driven with a single function, window.globatics(command, …args). Calls made before the script loads are queued by the stub from the install snippet and replayed in order.
Script attributes
| Attribute | Default | Effect |
|---|---|---|
data-site | required | Site id. Without it the script does nothing. |
data-api | <script origin>/api/collect | Collect endpoint. Use it with a first-party proxy. |
data-persist | off | Stores a random visitor id in localStorage (globatics_vid) so returning visitors and retention work across days. Turned off by Global Privacy Control. |
data-hash | off | Hash routing: /#/page changes count as pageviews and the hash is kept in URLs. |
data-exclude | — | Comma-separated path globs that are never tracked: /admin/*,/preview/**. * is one segment, ** is anything. Case-insensitive. |
data-include | — | Only these path globs are tracked (same syntax). Leaving them with a client-side navigation sends leave. |
data-auto="false" | auto | No automatic pageviews: call globatics('pageview') yourself. |
data-respect-dnt | off | Disables tracking when the browser sends Do Not Track. |
data-clicks="false" | on | Disables $click, $rage_click and $dead_click. Link tracking stays on. |
data-errors="false" | on | Disables $error. |
data-vitals="false" | on | Doesn’t load /vitals.js. |
Example
<script defer
data-site="SITE_ID"
data-persist
data-exclude="/admin/**,/preview/*"
src="https://globatics.live/script.js"></script>JavaScript commands
globatics(command, …)
// custom event, optional props (flat, max 30) and revenue
globatics('event', 'purchase', { plan: 'pro', seats: 3 }, { revenue: 49.9, currency: 'EUR' });
globatics.track('signup', { plan: 'free' }); // same as 'event'
// identify the visitor (needs "Allow identify" in site settings; ignored under GPC)
globatics('identify', 'user_123', { name: 'Ada', plan: 'pro' });
globatics.identify('user_123');
globatics('reset'); // on logout
// manual pageviews (data-auto="false", or virtual pages)
globatics('pageview'); // current URL
globatics('pageview', '/checkout/step-2'); // relative or absolute URL
globatics.pageview('/virtual');
// owner opt-out for this browser (stored as localStorage "globatics_ignore")
globatics('optout');
globatics('optin');Collected automatically
| Signal | When | Data |
|---|---|---|
| Pageview | Initial load, pushState / replaceState / popstate (same URL deduped), hash changes with data-hash, back/forward-cache restores. | URL, referrer (first view), title, screen size, language, timezone |
| Heartbeat | Every 15 s while the tab is visible, and at once when it becomes visible again. | Engaged time, scroll depth |
| Leave | Page hidden or pagehide (never unload). | Final engaged time and scroll depth |
$outbound | Click on a link to another site. | URL |
$download | Click on a file link (pdf, zip, dmg…). | URL, extension |
$mailto / $tel | Click on an e-mail or phone link. | URL without the query |
$click | Clicks on links, buttons and submit inputs; at most 50 per page. | Selector, label (32 chars, digits and e-mails masked), x/y in % of the viewport |
$rage_click | 3 or more clicks, each within 30 px and 1 s of the previous one. | Selector, label, x/y, click count |
$dead_click | A click on a button-like element with no DOM change, scroll, focus move or navigation within 2.5 s. | Selector, label, x/y |
$error | Uncaught errors, failed resources, unhandled rejections; at most 5 per page. | Message (300 chars), source, line, column, 3 stack frames, ms since the last click |
$form_submit | Any form submit (never the values). | Form id, name or action |
$search | A pageview with ?q=, ?s= or ?search=. | Query, 64 chars, masked |
$vitals | Once, when the page is first hidden (from /vitals.js). | LCP, FCP, INP, CLS, TTFB |
Never collected
The script never reads what someone types: input values and contenteditable content are never read, and hash fragments are dropped unless you use data-hash.
Limits
| Item | Limit |
|---|---|
| Event names | 1–100 characters; must not start with $ (reserved) |
| Props | Flat values: string (≤ 256 chars), number, boolean or null. Keys ≤ 64 chars, at most 30 props. |
| Revenue | Major units (49.9). Negative values (refunds) allowed; outside ±1,000,000,000 dropped. |
| Currency | ISO 4217 code; the site currency when missing. |
| Request body | 8 KB of UTF-8; props are dropped beyond that. |
| URLs | 2,048 characters |
Content Security Policy
Allow your Globatics host in script-src and connect-src. With nonce-based CSP, use 'strict-dynamic' so vitals.js can load, or set data-vitals="false". If you proxy everything through your own domain, 'self' is enough.