Coding assistants

Instructions for an AI coding assistant to add fivebar to a site, from the tag to events.

An assistant working in your site’s code can read its templates, so it puts the tag where every page gets it and adds what your site needs beyond it, such as the status on error pages or an event for each sign-up. It takes one paste from you. The sections below are written for the assistant.

Open your assistant in the project that builds your site, press Copy instructions at the top of this page, choose Copy instructions in its menu, and paste them in. If your assistant can read the web, this line is enough:

Add fivebar analytics to this site, following https://fiveb.ar/docs/coding-assistants.md

It asks for anything it can’t work out, such as the domain. Review its changes as you would anyone else’s.

What you’re adding

fivebar is web analytics without cookies. A site is counted by one script tag, the same on every page, loaded from fiveb.ar. There’s no package to install and no server code. Each link below is to a page with the details, which you can read as Markdown.

The site’s owner adds it to fivebar first, and the domain it was added under goes in the tag’s data-domain. If you’re connected to fivebar over MCP, get_site_setup gives you the site’s tag with its domain filled in. Otherwise, if you can’t tell the domain, ask.

Add the tag

Put this in the <head> of every page, once, with the site’s domain in place of example.com:

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

• Add it to the layout, template or theme every page shares. Platforms says where that is for WordPress, Next.js, Astro, Hugo, Vite, Nuxt, SvelteKit, Google Tag Manager and more.
• Keep async, data-domain and the src as written. The script sends to the host it was loaded from, so don’t bundle it or copy it into the project. To serve it from the site’s own domain, set up a proxy as Proxying says, only if the owner asks for one.
• Don’t delay it until the visitor scrolls or clicks, or move it into a web worker such as Partytown. A visitor who leaves first isn’t counted.
• A single-page app needs nothing more: the script counts each page the app moves to. See Single-page apps.

Add what the site needs

Look through the site for each of these, and add the ones that apply.

Error pages

On each template that answers with an error status, such as a 404 or 500 page, add data-status to the tag with the status, such as data-status="404", from the variable the template has for it. Safari needs it to tell errors from ordinary pages. See Error pages.

Private paths

Where addresses hold anything private, such as a token in a sign-in link or an account’s name, set data-path to the path to count the page under, such as data-path="/login/:token", or data-path="/:account/*" for every page under an account. See data-path.

Custom properties

Only if the owner wants them: data-property- attributes label each page with what its template knows, such as data-property-author="Ada Lovelace". Never anything about the visitor. See Custom properties.

Events

Only for actions the owner wants counted, such as a sign-up or a purchase: ask which, if it isn’t clear. Each event is a goal on the dashboard. On anything clicked:

<button data-tally="Signup" data-tally-plan="pro">Start</button>

Or from code, such as once a form has been accepted:

tally('Signup', { plan: 'pro' });

Custom events covers calling it before the script has loaded, and the names and data an event can have. Pageviews, links to other sites and downloads are counted already, and a thank-you page is a goal the owner adds in the site’s settings, with no code: see Goals.

Links

If the site’s links lead somewhere that shouldn’t be followed, such as an app’s links to its customers’ own sites, add data-links="off" to the tag. See Outbound links and downloads.

Site search

Only if the site has a search of its own and the owner wants it counted. A search page whose address holds the search, such as /search?q=shoes, needs no code: the owner adds a rule in the site’s settings. Where the address doesn’t hold it, such as a results page answering a form, add data-search to the tag on the results template, with the search as typed, such as data-search="{{ query }}", and leave it out elsewhere. Either way, add data-search-results with the number of results shown, such as data-search-results="{{ count }}", so a search that found nothing is marked. See Site search.

Content Security Policy

Look for one wherever the site sets headers or meta tags: framework or server config, middleware, vercel.json, netlify.toml, a _headers file, Helmet, or a <meta http-equiv="Content-Security-Policy">. If there is one, allow https://fiveb.ar for loading scripts and for connecting, as Content Security Policy explains, nonces and default-src included.

Leave these out

data-local is for testing the script, and stops a live site being counted properly. Leave data-api out too, unless the site serves the script from its own domain at other paths, when it says where the counts go. Don’t add a second copy of the tag, or a wrapper of your own around it. Script attributes lists every attribute.

Check it works

1. Build the site, and check the tag is in the <head> of several kinds of page, once each, with the right data-domain.
2. Nothing is sent from localhost or a file, so check the deployed site: each page sends a request to https://fiveb.ar/api/tally, answered 202. If nothing is counted says what any other answer means.
3. Connected over MCP, call check_install once it’s deployed. It reads the home page and says whether the tag is there, whether the Content Security Policy lets it through, and what has been counted, with what to do about anything wrong.
4. Tell the owner what you added and where, including any events, properties and data-path patterns, and what’s left for them to do in fivebar, such as adding page goals or search rules.