Skip to content

Script tag ​

This works on any site, with or without a framework. Set up the /_t/* rewrite first, then add the tag to every page, ideally in <head>:

html
<script defer src="/_t/t.js" data-site="mysite"></script>

data-site must match a site id from Settings → Add site in the dashboard (or TRAIL_SITES). That is all you need for pageviews, single-page-app navigation, time on page, scroll depth and outbound link clicks. By default the tracker is private until the visitor consents; see Privacy modes.

Attributes ​

AttributeDefaultWhat it does
data-siterequiredSite id from Settings (or TRAIL_SITES)
data-api/_t/eWhere events are sent. Set a full URL only if you cannot add a rewrite
data-envderived by the serverTag events, e.g. production or preview. See Environments
data-devoffAlso track on localhost, 127.* and [::1]
data-routenoneRoute template for pageviews, such as /blog/[slug], so the dashboard can group them
data-modeprivate until consentfull stores an id from the first page; private never stores anything. See Privacy modes
data-dnthonour the signalsoff tracks visitors who send Do Not Track or Global Privacy Control. See DNT and GPC
data-vitalsoffReport web vitals
data-rageoffReport rage clicks
data-formsoffReport form submits: the form's id or name, never field values
data-errorsoffReport JavaScript errors, at most 5 distinct ones per page load

On/off attributes are on when present, whatever their value: data-dev and data-dev="1" mean the same.

The last four load a small second file, t.x.js, only when one of them is set. See Extras.

To name clicks on buttons and links without code, add data-trail="Name" to the element itself, not to the script tag. See Named clicks.

Add a site ​

Open Settings in the dashboard, click Add website and enter the domain, such as example.com. Trail suggests a site id. That id goes in data-site and cannot change later. The site's Install panel has copy-ready code filled in with your id and Trail host. You can also seed sites at startup with TRAIL_SITES=id=domain,.... See Settings for the rest.

Origins that can send events ​

/_t/e accepts events for a site only from its own domain, its subdomains, hosts on the site's allowed-origins list (up to 20, wildcards such as *.vercel.app work) and localhost. Anything else gets an empty 403. A rewrite on your own domain still works. The full rules and the rejected24h counter are in Allowed origins.

The private-only file ​

/_t/t.p.js takes the same attributes except data-mode. It never stores anything in the browser and leaves out identify, consent upgrades and named clicks, which makes it smaller:

html
<script defer src="/_t/t.p.js" data-site="mysite"></script>

Load and caching ​

Trail serves t.js gzipped to browsers that accept it, with an ETag, so a repeat visit gets a 304. It is cached for an hour (Cache-Control: public, max-age=3600).

Calls before the script loads ​

The tag is defer, so code that runs earlier cannot call trail yet. Define a small queue and Trail replays it when it starts:

html
<script>
  window.trail = window.trail || function () { (window.trailq = window.trailq || []).push(arguments); };
</script>
<script defer src="/_t/t.js" data-site="mysite"></script>

Before the tracker loads, call the stub with the method name first, as in trail('track', 'Signup', { plan: 'pro' }). Once it has loaded, window.trail is the real API: trail.track('Signup'). If the same code can run on either side of that moment, the npm package handles both for you.

Avoid double pageviews with the script tag ​

The tracker records a pageview on load, on every history.pushState, and on back and forward navigation. Do not also call trail.pageview() on route changes, or each navigation counts twice. Call it yourself only when the URL does not change but you want a new view, such as a modal that acts as a page.

Check the tag ​

Open the page and look in the network panel for POST /_t/e with status 204. The site's Install panel under Settings switches from "Waiting for the first event…" to "Receiving data", and the header shows 1 online. If nothing arrives, see Troubleshooting.

Next ​