TraceScript options
Every attribute you can add to the Trace script tag to change what it records and where it sends data.
Every option is a data-* attribute on the script tag. Boolean options are turned on with the value "true".
<script
defer
data-website-id="YOUR_WEBSITE_ID"
data-domain="example.com"
data-allowed-hostnames="checkout.example.com"
data-disable-form-tracking="true"
src="https://data.whos1.bid/script.js"
></script>Core
| Attribute | What it does |
|---|---|
data-website-id | Required. Which site the data belongs to. |
data-domain | Required. Your site's domain. Events from other domains are rejected. |
data-allowed-hostnames | Comma-separated extra hostnames that count as your site (for example a checkout on another domain). A visitor keeps one identity across them, and links to them aren't counted as outbound. |
data-api-url | Send events to a custom endpoint instead of Trace's — for example a first-party proxy on your own domain. |
Environments
| Attribute | What it does |
|---|---|
data-allow-localhost | Set to true to track on localhost and other local hostnames. |
data-allow-file-protocol | Set to true to track pages opened from file://. |
data-debug | Set to true to log what the script does to the browser console. |
data-disable-console | Set to true to silence all of the script's console messages. |
Navigation
| Attribute | What it does |
|---|---|
data-hash-based-routing | Set to true to treat #/route changes as page navigations (for older single-page-app routers). |
Automatic tracking
| Attribute | What it does |
|---|---|
data-disable-file-downloads | Stop automatic file_download events. |
data-file-types | Replace the list of file extensions that count as downloads, for example pdf,csv. |
data-add-file-types | Add extensions to the download list. |
data-disable-form-tracking | Stop automatic form_submission events. |
data-disable-engagement-tracking | Stop the scroll-depth and time-on-page ping sent when a visitor leaves a page. |
data-disable-payments | Stop automatic detection of returns from a Stripe, Polar or Lemon Squeezy checkout. |
The default download extensions are: pdf, xlsx, docx, txt, rtf, csv, exe, key, pps, ppt, pptx, 7z, pkg, rar, gz, zip, avi, mov, mp4, mpeg, wmv, midi, mp3, wav, wma and dmg.
Session replay
These only matter when session replay is turned on for the site.
| Attribute | What it does |
|---|---|
data-disable-replay | Set to true to never record pages carrying this script tag (for example a checkout). |
data-replay-sample-rate | Override the dashboard's sample rate (0–100) on these pages. |
data-replay-mask-all-text | Set to true to mask every piece of text on the page, not just inputs. |
data-replay-block-selector | Extra CSS selectors to leave out of recordings entirely. |
data-replay-mask-selector | Extra CSS selectors whose text is masked. |
Using a first-party proxy
By default the script sends events to the same origin it was loaded from. If you serve script.js through your own domain (a reverse proxy or a framework rewrite), events go back through that same proxy automatically. Use data-api-url only when the collect endpoint lives somewhere else.
A proxy should forward the visitor's User-Agent, Accept-Language, Origin, Sec-Fetch-* and X-Forwarded-For headers. Without them, real visitors can be mistaken for bots and locations can't be worked out. If you use session replay, forward /replay.js and /api/replay/* as well as /api/collect.