Skip to content

The tracking snippet

Add this to every page, typically in the shared layout, with your instance's hostname:

<script defer src="https://analytics.example.com/t.js"></script>

Every site uses this same snippet: the server assigns each hit to the project that claims the page's hostname. The Tracking page of each project's settings shows it too.

The script is short and readable. On each page view it sends the URL, the referrer, the page load time, whether the browser is automated, the screen's width as a class (phone, tablet, laptop or desktop, never the width itself) and the browser's language (fr, not fr-CA). Heartbeats follow every 15 seconds while the page is visible, plus one when it is hidden: they measure time on page. Each heartbeat sends how far down the page was scrolled. It also sends the Core Web Vitals measured so far, LCP, INP and CLS: how fast the page showed, answered and settled. It stores nothing in the browser, except the objection of a visitor who opts out.

Single-page applications

Route changes made with history.pushState are counted as page views automatically. To send them yourself instead, add data-auto-track="false" to the script tag and call window.abilianAnalytics.pageview() after each navigation.

Not-found pages

To count the views of a site's "not found" page as such, add data-404 to the page's <html> or <body>,

<body data-404>

or call window.abilianAnalytics.notFound() from the page, for a single-page application whose router shows the page.

The report then lists those addresses on the Not found card, with the links that led there.

The snippet counts clicks on links to other sites as Outbound link events, and clicks on links to files of the site (PDF, archives, office documents, audio and video, installers) as File download events, with no markup. Each records the link's address, without its query string, as its url: filter the report by the event to see which links and files. Middle clicks count too.

To count neither, add data-outbound="off" to the script tag:

<script defer src="https://analytics.example.com/t.js" data-outbound="off"></script>

A link with a data-event attribute counts as that event only.

Custom events

To count what people do besides viewing pages, such as sending a form or opening a menu, add a data-event attribute, with a name of your choice, to the link or button they click. For example, to count sign-ups:

<button data-event="Signup" data-event-plan="pro">Sign up</button>

Each attribute whose name starts with data-event- records a detail with each click: here, data-event-plan records which plan was chosen, and the report then breaks Signups down by plan. From your own code:

window.abilianAnalytics.track("Signup", {plan: "pro"})

An event keeps its name (64 characters) and up to 10 properties, each a short string; never put anything personal in them. A visit that sends an event is not a bounce.

Letting visitors opt out

Visitors must be able to object to being counted, and be told so. The Privacy page of the project's settings offers a privacy notice, in English and French, to paste into your privacy page: what is measured, how long visits are kept and how to object, filled from the project's settings, with the switch below. Or put the switch alone on your privacy page, where the snippet already loads:

<div data-aa-optout></div>

The snippet fills it with a checkbox, ticked while the browser's visits are counted:

☑ My visits are counted in this site's audience measurement (visit statistics, no cookie). Untick to stop: your choice is kept in this browser.

Unticking it stores the objection in the browser's local storage for this site, under the key abilian-analytics:opt-out. From then on, this browser sends nothing: no page views, events or heartbeats, on any page of the site, until the visitor ticks the box again. Nothing is stored for visitors who don't object.

  • Language: the texts are in French when the page's lang starts with fr, in English otherwise. Attributes replace them, for another language or another tone: data-aa-optout-label (the checkbox's label), data-aa-optout-counted and data-aa-optout-stopped (the line under it, ticked and unticked), data-aa-optout-unavailable (see below).
  • Style: the markup is an unstyled label and p, inside the element, which gets the class aa-optout; the line is aa-optout__status.
  • Without JavaScript, the element keeps what you wrote in it, for instance a sentence on Global Privacy Control.
  • Seen in the settings: the Sites card, on the General page of the project's settings, shows, for each site, the last page where a counted visit saw the switch, and when. Visits that aren't recorded, such as those from the project's ignored networks, don't report it.
  • One site at a time: the browser keeps the choice for the site's address only. If a project counts www.example.com and shop.example.com, show the switch on each.
  • Browsers that refuse storage, in some private modes, can't keep the choice. The checkbox is then disabled. The line under it suggests Global Privacy Control instead, which projects respect by default.

A site with a consent interface of its own can use the same choice from its code:

window.abilianAnalytics.optOut()     // true once the objection is stored
window.abilianAnalytics.optIn()
window.abilianAnalytics.isOptedOut()

Pages without JavaScript

Add an image, which the browser loads without running any script:

<noscript><img src="https://analytics.example.com/t.gif" alt=""></noscript>

Browsers usually send only the site's origin to another site, so these hits count for the home page.

Content-Security-Policy

A site with a Content-Security-Policy must allow the instance's origin in script-src, for the script, and in connect-src, for the hits.

Checking it works

After a visit in a normal browser window, the project's report shows it within seconds, under "Online now". Nothing shows?

  • Administration → Unclaimed hostnames: a hostname listed there sends hits, but no project claims it. Attach it.
  • The browser's developer tools show whether t.js loaded and whether the POST to /t was blocked, by the CSP or an ad blocker.