The tracking snippet¶
Add this to every page, typically in the shared layout, with your instance's hostname:
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>,
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.
Outbound links and downloads¶
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:
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:
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:
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:
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
langstarts withfr, in English otherwise. Attributes replace them, for another language or another tone:data-aa-optout-label(the checkbox's label),data-aa-optout-countedanddata-aa-optout-stopped(the line under it, ticked and unticked),data-aa-optout-unavailable(see below). - Style: the markup is an unstyled
labelandp, inside the element, which gets the classaa-optout; the line isaa-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.comandshop.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:
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.jsloaded and whether the POST to/twas blocked, by the CSP or an ad blocker.