Matomo AI Bot Tracking

Server-side tracking of AI assistants and chatbots (ChatGPT, Claude, Perplexity, etc.) for Matomo Analytics.

AI assistants fetch pages over plain HTTP and never execute JavaScript, so the Matomo module's client-side tracking code never fires for them. This module detects those requests by their User-Agent and sends a server-to-server beacon to Matomo's HTTP Tracking API instead, using the Bot Tracking parameters introduced in Matomo 5.7.0.

• https://developer.matomo.org/api-reference/tracking-api#tracking-bots
• https://matomo.org/faq/how-to/set-up-ai-chatbot-tracking-with-the-http-tracking-api/

• The Matomo module, configured with a valid site ID and server URL. This module reads both from matomo.settings and does not duplicate them.
• Matomo 5.7.0 or later on the server side.

• Install this module using the official Backdrop CMS instructions at https://backdropcms.org/guide/modules
• Configure the parent Matomo module first, at admin/config/system/matomo.
• Visit admin/config/system/matomo/ai-tracking and enable AI bot tracking.

At admin/config/system/matomo/ai-tracking:

• Enable AI bot tracking — master switch.
• User-Agent patterns — a case-insensitive regular expression fragment, alternatives separated by | or one per line. The form rejects invalid regular expressions and patterns that would also match regular browsers (for example an empty alternative such as a trailing |), since those would report every visitor as a chatbot. Leave empty to use the built-in default list, which mirrors the User-Agents Matomo currently classifies as live, user-triggered AI chatbots. Matomo decides chatbot classification on its own side: adding training or indexing crawlers (GPTBot, ClaudeBot, CCBot…) forwards those requests but they will not appear in the AI Chatbots reports.
• token_auth — optional, only needed if you want the visitor IP recorded. Matomo requires authentication for the cip parameter.

AI bots rarely carry a session cookie, so Backdrop's internal page cache serves their requests directly and the request exits before hook_init() or hook_exit() run. This module uses hook_boot(), the earliest hook available.

Backdrop does not invoke hook_boot() on page cache hits by default. Without the setting below, tracking only fires on the first request after each cache clear or expiry for a given URL, so a bot crawling fifty pages may show up as a single hit. To cover cached pages, add this to settings.php:

$settings['page_cache_invoke_hooks'] = TRUE;

This setting is not scoped to this module. It makes Backdrop invoke hook_boot() and hook_exit() for every bootstrap module on the site, in a phase where common.inc and most module APIs are not yet loaded. Modules that implement those hooks assuming a full bootstrap will throw a fatal Call to undefined function error, visible only to anonymous users.

Three known cases:

• devel — devel_exit() fails. Devel should not be enabled on a production site anyway.
• gdpr_cookies — gdpr_cookies_exit() fails in versions before 1.x-1.3.7. Fixed upstream in issue #66; update to 1.x-1.3.7 or later.
• statistics — statistics_exit() fails in versions before 1.x-1.2.0, which also adds the missing accesslog.user_agent column. Update to 1.x-1.2.0 or later and run update.php.

If you enable this setting, check which modules are involved with:

SELECT name, type FROM system WHERE bootstrap = 1 AND status = 1;

Bugs and feature requests should be reported in the issue queue.

• Robert Garrigos (https://github.com/robertgarrigos)

This project is GPL v2 software. See the LICENSE.txt file in this directory for complete text.