Tracker reference
The tracker is the script that your pages load from your instance. It sends pageviews, time on page, custom events, errors, and Web Vitals, and clicks and scroll depth for heatmaps when you ask for them. It stores nothing on the visitor’s device.
The tracker itself is about 5.0 KB, gzipped. It loads its other scripts only when a page needs them. See Scripts beside the tracker.
The script tag
Section titled “The script tag”Put this tag in every page, with your instance’s address and the project’s public key:
<script defer src="https://analytics.example.com/t.js" data-key="pk_…" data-host="https://analytics.example.com"></script>- Keep
defer. The script then loads after the HTML and does not block the page. - The instance serves the script at
/t.js. Browsers can cache it for one hour. - Without
data-keyordata-host, the tracker sends nothing and writes a warning in the console.
Attributes
Section titled “Attributes”| Attribute | Value | What it does |
|---|---|---|
data-key |
pk_… |
Required. The project’s public key. |
data-host |
https://analytics.example.com |
Required. The instance’s address. The tracker sends events to /api/events there. |
data-environment |
Such as staging |
The environment. 1 to 64 letters, digits, ., _, or -, starting with a letter or digit. Without it, events count as production. If the value is not valid, the tracker sends nothing. |
data-release |
Such as 1.4.2 |
Your app’s version. 1 to 200 characters, without spaces or control characters. If the value is not valid, the tracker leaves it out. Source maps need it. |
data-user-id |
Such as 42 |
Your app’s ID for the signed-in user. See Name signed-in users. |
data-user-signature |
64 hex digits | The user ID’s signature, made by your server. See Sign user IDs. |
data-errors |
off |
Turns off the automatic report of uncaught errors and unhandled rejections. captureError() still works. |
data-vitals |
off |
Turns off Web Vitals. The tracker then does not load v.js. |
data-replay |
errors |
Records the moments before an error, when the project’s settings allow replays too. The tracker then loads r.js. |
data-replay-consent |
wait |
With data-replay, the tracker loads no recorder until the page calls replay(true), after the visitor agrees. See Turning it on. |
data-replay-text |
show |
Shows the page’s text in replays. By default, text is masked. |
data-replay-media |
show |
Shows images and media in replays. By default, they are blocked. |
data-heatmaps |
on |
Records clicks and scroll depth for heatmaps, when the project’s settings allow heatmaps too. The tracker then loads h.js. See Heatmaps. |
data-heatmaps-sample |
A number from 0 to 1, such as 0.25 |
With data-heatmaps, records this share of pageviews. Without it, every pageview is recorded. A value outside 0 to 1 writes a warning in the console, and every pageview is recorded. |
Markers in your HTML
Section titled “Markers in your HTML”Put these attributes on elements in your own HTML:
| Attribute | What it does |
|---|---|
data-ottertrail-mask |
In replays, masks the element’s text. For heatmaps, clicks inside the element are not recorded. |
data-ottertrail-block |
In replays, leaves the element out: the replay shows only a box of its size. For heatmaps, clicks inside the element are not recorded. |
data-ottertrail-unmask |
In replays, shows the element’s text, while the rest of the page is masked. It has no effect on heatmaps. |
data-ottertrail-name |
For heatmaps, a name for the element, such as hero-cta. Clicks on the element and inside it are listed under this name. 1 to 64 letters, digits, spaces, ., _, :, /, or -, starting with a letter or digit. Never put personal data in it. See Naming elements. |
In replays, typed values never leave the page, and canvas, frames, object, and embed elements are always blocked. See Masking and privacy.
Scripts beside the tracker
Section titled “Scripts beside the tracker”The tracker loads its other scripts from beside its own address, only when a page needs them:
| Script | What it does | Loaded when |
|---|---|---|
v.js |
Measures Web Vitals | On every page, unless the tag has data-vitals="off" |
r.js |
Records session replays | The tag has data-replay="errors" |
h.js |
Records clicks and scroll depth for heatmaps | The tag has data-heatmaps="on", with the first pageview in the sample |
o.js |
Draws the heatmap over the page for a member of your team (about 6.8 KB, gzipped) | The page was opened with Open on your site from the dashboard (below) |
- If the tag has an
integrityattribute, the tracker loads none of these scripts. They cannot be pinned with it. So a pinned tracker sends no Web Vitals, records no replays or heatmaps, and shows no heatmap overlay. - If the tag has a
nonce, the tracker gives the same nonce to each script. This supports a strict Content Security Policy.
The heatmap link
Section titled “The heatmap link”Open on your site, on the dashboard’s Heatmaps report, opens a page of your site with #ottertrail-heatmap= and a token at the end of its address. When the tracker sees it, it:
- removes the fragment from the address, and keeps the rest of the address;
- loads
o.js, which asks your instance whether the link is valid; - holds the page load’s events, for at most 5 seconds, until the answer.
For a valid link, o.js draws the heatmap, and the tracker sends nothing for the rest of that page load. For anything else, such as a made-up token or a link already used, the tracker sends the events it held and carries on as usual. See Open the heatmap on your site.
JavaScript API
Section titled “JavaScript API”The tracker adds window.ottertrail. Calls made before the script loads are lost, so call it with ?.:
window.ottertrail?.track("signup", { plan: "free" });| Function | What it does |
|---|---|
track(name, properties) |
Sends a custom event. properties is optional. |
identify(userId, signature) |
Events from now on carry this user ID. signature is optional. Use it in single-page apps when a user signs in. |
reset() |
Events from now on are anonymous. Use it when a user signs out. |
captureError(error, properties) |
Reports an error that your code caught. properties is optional. See Report errors from the browser. |
replay(true) |
Starts session replay after the visitor agrees, on a tag with data-replay. Calling it again while recording does nothing. |
replay(false) |
Stops session replay and drops what was recorded, or cancels a start still waiting. A replay already sent stays sent. The last call wins: replay(true) afterwards starts a new recording. |
Custom events
Section titled “Custom events”- Name: 1 to 200 characters. The tracker removes control characters and cuts longer names.
- Properties: a flat object. Values are strings, numbers, booleans, or
null. At most 30 keys of up to 100 characters each. Strings are cut to 500 characters. At most 8 KB in total. - Reserved names:
pageview,engagement,error, andvitalsare the tracker’s own events.track()refuses them and writes a warning in the console.
What the tracker sends
Section titled “What the tracker sends”| Event | When |
|---|---|
pageview |
When the page loads, and when the path changes without a page load. A change only to the query string or the fragment is not a new pageview. |
engagement |
When the visitor leaves a page or hides the tab: the time the page was visible. Less than one second is not sent. |
error |
An uncaught error, an unhandled rejection, or a captureError() call. |
vitals |
One for each page load, when the page is first hidden or left: LCP, INP, CLS, FCP, and TTFB, as measured until then. |
| Custom events | Each track() call. |
With data-heatmaps="on", h.js sends each recorded pageview’s clicks and its scroll depth to /api/heatmaps, in batches: a batch leaves when 50 records wait or 5 seconds have passed, and when the page is hidden or left. These are not events: they have no visitor ID, and they do not count as pageviews. See Heatmaps.
Single-page apps
Section titled “Single-page apps”- The tracker sees path changes from
history.pushState,history.replaceState, and the back and forward buttons. - Routers that change only the fragment, such as
/#/pricing, record every page as/. - A page that the browser restores from its back/forward cache counts as a new pageview.
- A page that the browser prerenders counts only when the visitor sees it.
Privacy
Section titled “Privacy”- Page addresses are cut to their origin, path, and UTM tags (
utm_source,utm_medium,utm_campaign,utm_term,utm_content) before they are sent. - Referrers are cut to their origin and path.
- The user ID stays in memory only, for the current page load.
Sending
Section titled “Sending”- Events wait up to one second, then leave together in one request.
- When the instance does not answer, or answers 429 or 5xx, the tracker tries again, with waits from about 1 to 60 seconds. After 8 failed attempts, it drops the batch. It follows the instance’s
Retry-After. - When the instance refuses a batch (400, 403, 413, or 415), the tracker drops it.
- The queue holds at most 200 events. When it is full, the oldest events go first.
- When the tab is hidden or the page closes, the tracker sends what is waiting with
navigator.sendBeacon.
The request format is in the HTTP API reference.