Script attributes

The script takes its settings from attributes on its own tag. Only data-domain is needed.

The rest are for when a site needs more: marking error pages for Safari, keeping a token in an address out of your stats, counting what visitors search for, labelling pages with their author, or not counting clicks on links. Each is one attribute on the tag you already have.

<script async data-domain="example.com" src="https://fiveb.ar/js/tally.js"></script>

The src is always https://fiveb.ar/js/tally.js. It’s updated in place, so there’s nothing to upgrade. async keeps the script from holding up the page.

On the tag

The script reads these once, as it loads, so changing them later does nothing. The exceptions are data-path, data-search and data-search-results, which it reads for every pageview.

data-domain

The site to count the page under, as you added it to fivebar, such as example.com. Capitals and a leading www. are ignored. The page must be on that domain or one of its subdomains, or what it sends is refused.

Leave it out and the page’s own hostname is used, which only works on a page at the site’s exact domain. The tag a site’s settings give always has it.

data-status

The HTTP status the page was served with, such as 404. Put it on error pages, where Safari needs it to tell an error from an ordinary page: see Error pages. Only a whole number from 100 to 599 is read.

data-path

The path to count the page under in place of its own, for addresses that hold something that doesn’t belong in your stats, such as the code in a sign-in link or an account’s name. It has to start with /, or it’s ignored. data-path="/login/:token" counts /login/8f3kq2 as /login/:token, along with everything the page sends: its events, clicks, speed and reading. The query string is kept, for its campaign tags and site search.

Ending in /*, it replaces as many parts of the path as it has before the * and keeps the rest: data-path="/:account/*" counts /acme/settings as /:account/settings. It’s read for every pageview, so a single-page app can change it as it moves.

data-search

What the visitor searched for, on a results page whose address doesn’t hold it, such as one answering a form: data-search="red shoes" counts a search for red shoes on the page. It’s counted on any page that has it, whatever the site’s search rules say, and read for every pageview, so a single-page app can set it before it moves. See Site search.

data-search-results

How many results the page shows, such as data-search-results="0", which marks the page’s search as one that found nothing. It counts only beside a search, from data-search or a search rule, and only a whole number of up to 9 digits is read. See Site search.

data-property-<name>

A custom property of the page, sent with everything it counts: data-property-author="Ada" counts the page’s views under the author Ada. A tag can have up to 8. See Custom properties.

data-links

data-links="off" stops the page counting clicks on links to other sites and to files, for links you’d rather not follow, such as an app’s links to its customers’ own sites. Anything with data-tally still counts. Any other value leaves links counted.

data-local

The script sends nothing from a page on localhost, an address starting 127., 0.0.0.0 or [::1], or a page opened from a file, so a copy of the site on your own computer is never counted. data-local makes it send from those too, whatever its value, even "false".

fivebar still refuses what a local page sends, since it isn’t on the site’s domain. The attribute is for watching the script’s requests in your browser’s developer tools while you work.

data-api

Where the script sends what it counts. It defaults to /api/tally on the host the script was loaded from: https://fiveb.ar/api/tally, or your own domain’s through a proxy. Set it when your proxy takes the counts at another path, such as data-api="/stats/event". Only fivebar counts anything, so wherever it leads has to pass them on to fivebar.

On other elements

data-tally="Signup" on a button, a link or anything else that can be clicked sends that event when it’s clicked, with the element’s data-tally-<name> attributes as the event’s data. See Custom events.