Install
Three ways in — a script tag, the npm package, or your own server as a proxy. They record the same things; they differ in how much of your traffic survives an ad blocker.
Pick one
| Best for | Accuracy | |
|---|---|---|
| Script tag | Any site, any platform, no build step | Blockable by extensions |
| npm package | React, Next, Vue, Svelte, Astro, anything bundled | Nothing separate to block |
| Same-origin proxy | Either of the above, on your own domain | Best, and a 400-day cookie in Safari |
The honest summary: the script tag is the convenient install and the npm package behind a same-origin proxy is the accurate one. trckable will not tell you it is unblockable — nothing is.
The site id
Every site has an id like tkb_a1b2c3d4. It is not a secret: it appears in your
page source, the same way every analytics id does. It only says which site an
event belongs to, and the server checks the hostname the event came from.
The script URL
https://stats.example.com/js/tkb_a1b2c3d4.jsThat is your site's own build. It contains the features its modules turn on and nothing else, so a site that only counts visits downloads 1,596 bytes rather than 2,045. Turning a module on or off changes it, and visitors pick the change up within the hour — the script is cached for 3,600 seconds.
/js/t.js also exists and always contains goals, outbound links and checkout
attribution. Use it only if you cannot put a site id in the path.
What the script does on the page
- Sends one small POST when a page is shown, and a short report each time it is hidden or left (time on page, scroll depth).
- Never blocks rendering: it is loaded with
deferand sends withkeepalive. - Touches no browser storage in cookieless mode. Otherwise it keeps one cookie (the visitor id) and a small queue in local storage, so events made offline or during a restart are sent later.
- Ignores localhost,
file:, iframes and automated browsers, unlessdata-devis set — and even then the server only accepts it from localhost.
Options
Every option is a data- attribute on the script tag, or a prop on the package.
| Attribute | Does |
|---|---|
data-site | The site id. Required |
data-api | Where to send events. Defaults to /api/e next to the script |
data-cookieless | No cookie, nothing stored. The server sets this for you in cookieless mode |
data-domain | Cookie domain, e.g. example.com to share visitors across subdomains |
data-dev | Allow localhost and iframes while you are developing |
Verify it
npx trckable doctor https://example.comIt checks that your site is served over HTTPS and that the events endpoint answers a browser's cross-origin check.
