studio-variable / kirby-light-anonymous-analytics
Cookieless audience measurement for Kirby, within the CNIL consent exemption: page views, visits, pages, referring sites, devices and countries, in a panel area
Package info
forge.studio-variable.com/studio-variable/kirby-light-anonymous-analytics.git
Type:kirby-plugin
pkg:composer/studio-variable/kirby-light-anonymous-analytics
Requires
- php: >=8.2
- ext-pdo_sqlite: *
- getkirby/composer-installer: ^1.2
- maxmind-db/reader: ^1.11
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Cookieless audience measurement for Kirby 4 and 5, with a « Statistics » area in the panel: summary, pages and origin. Built to stay within the French CNIL's consent exemption for audience measurement — no consent banner — provided the site shows the opt-out notice (see Compliance).
Installation
composer config repositories.light-anonymous-analytics vcs https://forge.studio-variable.com/studio-variable/kirby-light-anonymous-analytics.git
composer require studio-variable/kirby-light-anonymous-analytics
The plugin lands in site/plugins/light-anonymous-analytics. Forgejo serves no zip archive to Composer, so the plugin is cloned: in a project that commits its dependencies, delete site/plugins/light-anonymous-analytics/.git before committing, or Git records it as a nested repository.
Then:
- Include the tracking snippet in the
<head>of every public page, the error page included (its views are counted as pages not found):<?php snippet('light-anonymous-analytics') ?> Show the opt-out notice on the privacy policy (or legal notice) page, in one of two ways:
- the
light-anonymous-analytics-optoutblock, added to a blocks field:fieldsets: [heading, text, light-anonymous-analytics-optout]; - the snippet, in a template:
<?php snippet('light-anonymous-analytics-optout') ?>. Pass['heading' => 'h3']for another heading level (h2 to h6),falsefor none.
It renders a heading, what is measured and for how long (the
retentionoption), and a « measure my visits » checkbox, in the page's language on a multilingual site (en, fr, es, pt). A single-language site sets it with thelanguageoption, English otherwise.- the
- Set
'mode' => 'production'on the production server only (seemode). - If the panel menu is customised (
panel.menu), add theanalyticsarea to it. - Keep
site/analytics/out of Git and out of deployment mirrors: it holds the server's statistics.
Options
In site/config/config.php, all optional:
'studio-variable.light-anonymous-analytics' => [
'mode' => 'test', // 'test' (default) or 'production'
'geo' => true, // visits per country (default: false)
'timezone' => 'Europe/Paris', // time zone of the statistics (default: PHP's)
'root' => null, // storage folder (default: site/analytics)
'retention' => 'P25M', // statistics older than this are deleted
'language' => 'fr', // opt-out notice language on a single-language site (default: English)
'resolve' => null, // see below
],
mode
test, the default: statistics go toanalytics-test.sqlite, logged-in users are counted, and the panel shows a « Test mode » badge. A local or staging site never touches real statistics.production: statistics go toanalytics.sqlite, logged-in users are not counted.
Set production in the production host's config file only, for instance site/config/config.example.com.php:
return [
'studio-variable.light-anonymous-analytics.mode' => 'production',
];
retention
An ISO 8601 duration, 25 months by default: the longest the CNIL accepts, and what the 12-month view needs to compare with the year before. With less, the comparison is hidden where the previous period is no longer fully kept.
resolve
Visited pages are named after the Kirby page at their path (language prefix and translated slugs included), and grouped by their top-level page. For paths served by custom routes, resolve names them first; return null to fall back to the default lookup:
'resolve' => function (string $path): ?array {
if (str_ends_with($path, '/web') === false) {
return null;
}
$page = page(substr($path, 0, -4));
return $page ? ['title' => $page->title()->value() . ' (web)', 'page' => $page] : null;
},
Permissions
Every panel user sees the statistics, unless their role says otherwise:
# site/blueprints/users/editor.yml
permissions:
studio-variable.light-anonymous-analytics:
access: false
The menu entry, the view and the API route all follow it.
What the panel shows
- Summary: page views, visits, visitors per day, pages per visit and bounce rate, each compared with the previous period; visits or page views over time against the previous period; page views per weekday and hour; most visited pages and referring sites; devices.
- Pages: every visited page with its section, language, views, share, change, entries and trend, to filter, sort and compare; views per section and per language; pages not found.
- Origin: referring sites; with
geo, countries.
A period ends now, in the middle of its last hour, day or week; the previous period ends at the same point of its own, so that a partial day is compared with a partial day. The comparison is only shown when the previous period was fully recorded.
Definitions (also shown in the panel):
- page view: each display of a page;
- visit: a series of page views with no break longer than 30 minutes;
- visitor: the same connection and browser over a day. Two people on the same network with the same browser may count as one, and a visitor coming back another day is counted again;
- bounce: a one-page visit;
- entry: the first page of a visit.
Devices are told from the user agent: iPads that present themselves as a Mac (iPadOS 13 and later) are counted as desktops.
How it counts
- The tracking snippet (skipped for drafts and
?_tokenpreviews, and for logged-in users in production) sends asendBeaconPOST to/k/v— a neutral path, as ad blockers block URLs containing « analytics » — once the page has been visible for 1 s. It sends nothing after an opt-out, when the browser sends Global Privacy Control, or for automated browsers (navigator.webdriver). It sends the path, an HMAC token, the host of the previous page when it is another site, and withgeothe browser's time zone. - The token is an HMAC of the path and of its kind, page or not found: a beacon can't count a path the site didn't serve, nor turn a page into a page not found. It doesn't depend on the date, so pages served from a cache keep counting.
- The route drops a beacon with a foreign
Origin(www.or not), an opt-out cookie, aSec-GPC: 1header, a logged-in user in production, a bot user agent, an invalid token, or more than 30 hits a minute from the same fingerprint. It always answers 204. - The IP address is truncated first — last byte of an IPv4, /48 network of an IPv6 — and the full address is never used.
- Fingerprint: SHA-256 of the truncated IP, the user agent, the day and the site's secret. It tells a new visit from the next page of the same one. It is kept in the
visitorstable — with the time of the last view, the number of pages and the hour the visit started — and in thethrottletable for a minute, then deleted; the day's fingerprints are deleted the next day. It is never shown nor exported, and changes every day and from one site to another. - Statistics:
views(hour, path, count)andmetrics(hour, metric, value, count), in the configured time zone. Per hour:views,visits,visitorsandengaged(visits of more than one page). Per day: the per-visit dimensionsentry(path),referrer(host, '' for direct),deviceandcountry, andmissing(path of a page not found). - Old statistics are deleted once a day, by the first beacon or panel visit of the day.
- Storage: SQLite, with a
secretfor the token and the fingerprint, created on first use.
Countries (geo)
The country is looked up from the visitor's truncated IP address in the free DB-IP Country Lite database, and from the browser's time zone when the IP is unknown (local network, database unavailable). Neither is stored: only the country code, or « unknown », once per visit.
The database (~8 MB, dbip-country-lite.mmdb, next to the statistics) is downloaded by the server on first use, then each month — the server needs outbound HTTPS. Reading it requires maxmind-db/reader, installed with the plugin. It is licensed under CC BY 4.0: the panel view credits « IP Geolocation by DB-IP ».
Compliance
The script asks the browser to send information, so the ePrivacy rule on access to the terminal applies (EDPB Guidelines 2/2023, §33), cookie or not: no banner is needed because the measurement fits the CNIL's exemption for audience measurement (self-assessment tool, July 2025). How the plugin meets each criterion:
| CNIL criterion | Plugin |
|---|---|
| Purpose limited to the site's audience measurement, for the publisher only | Self-hosted, no third party, no export, no marketing feature (no campaign, conversion or acquisition channel) |
| Data minimised; at most page presence, feature use and timing events | Page presence only: path, referring host, device class, country |
| Referrer limited to the host; no UTM nor campaign identifier | The browser sends the host only; the path is stored without its query string |
| IP: city-level location at most, then at least the last byte removed | Truncated before any use; country only |
| Fingerprint with a site-specific and a time component | Site secret and day in the hash; deleted the next day |
| Anonymous statistics, whatever the selection; no tracking of a single user | Counts only, no visitor log, no filter combining dimensions. Per-visit dimensions are stored per day, apart from the hourly visit counts. Counts are not rounded to ten (see below) |
| Right to object, kept over time | Opt-out block or snippet; refusal kept in the laa_optout cookie (13 months), honoured by the script and the server; Global Privacy Control honoured by both |
| Users informed | Opt-out notice text, with the retention period |
| Retention: data 25 months at most | 25 months by default (retention); fingerprints one day |
About rounding. The CNIL suggests rounding counts to the nearest ten, or an analysis showing they are anonymous without it. Here, nothing in the statistics identifies a visitor: no identifier, no IP, no user agent, and the panel shows each dimension on its own, over a period of at least three days. On a very quiet site, a day with a single visit still shows that one visit's entry page, referrer, device and country side by side: someone who already knows that a given person visited that day could learn those four things about the visit, not who made it. Rounding would hide most of a small site's statistics; if this residual risk matters for your site, aggregate further before use.
Development
The panel view is a set of Vue single-file components in src/, built with kirbyup into index.js and index.css, which are committed:
npm install
npm run dev # rebuilds on change, with hot reload in the panel
npm run build # before committing
npm run lint
npm run format
PHP lives in lib/: Analytics (options, storage), Recorder (beacons), Stats (panel data), Pages (paths to pages), Geo (countries), and the area, routes and translations registered by index.php.
Upgrading
From 2.x
modetakes'production', no longer'prod'.- The token format changed: pages cached before the update stop counting until the cache is cleared.
- The default retention is 25 months instead of 13.
- Per-visit dimensions are stored per day from now on; earlier rows stay hourly and are read alike.
From 1.x
- Set
'mode' => 'production'in production before updating, or statistics go to the test database. - Show the opt-out notice on the privacy policy page.
- The
topoption is gone: every visited page is listed. - Countries are now counted once per visit, no longer per page view; earlier rows are kept as they are.
Licence
MIT