Search by

studio-variable / kirby-light-anonymous-analytics

isUnknown

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

Homepage

Type:kirby-plugin

pkg:composer/studio-variable/kirby-light-anonymous-analytics

Statistics

Installs: 3

Dependents: 1

Suggesters: 0

v3.1.3 2026-11-06 13:24 UTC

This package is auto-updated.

Last update: 2026-11-16 12:37:33 UTC


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:

  1. 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') ?>
    
  2. Show the opt-out notice on the privacy policy (or legal notice) page, in one of two ways:

    • the light-anonymous-analytics-optout block, 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), false for none.

    It renders a heading, what is measured and for how long (the retention option), 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 the language option, English otherwise.

  3. Set 'mode' => 'production' on the production server only (see mode).
  4. If the panel menu is customised (panel.menu), add the analytics area to it.
  5. 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 to analytics-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 to analytics.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 ?_token previews, and for logged-in users in production) sends a sendBeacon POST 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 with geo the 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, a Sec-GPC: 1 header, 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 visitors table — with the time of the last view, the number of pages and the hour the visit started — and in the throttle table 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) and metrics(hour, metric, value, count), in the configured time zone. Per hour: views, visits, visitors and engaged (visits of more than one page). Per day: the per-visit dimensions entry (path), referrer (host, '' for direct), device and country, and missing (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 secret for 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 criterionPlugin
Purpose limited to the site's audience measurement, for the publisher onlySelf-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 eventsPage presence only: path, referring host, device class, country
Referrer limited to the host; no UTM nor campaign identifierThe 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 removedTruncated before any use; country only
Fingerprint with a site-specific and a time componentSite secret and day in the hash; deleted the next day
Anonymous statistics, whatever the selection; no tracking of a single userCounts 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 timeOpt-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 informedOpt-out notice text, with the retention period
Retention: data 25 months at most25 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

  • mode takes '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 top option 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