Pagemetrics for Matomo
·
Pagemetrics for Matomo adds server-side, privacy-friendly analytics to WordPress. It tracks page views, downloads, and AI assistant bot crawls without …
Pagemetrics for Matomo adds privacy-friendly, server-side analytics to WordPress by
leveraging the pagemachine/matomo-tracking PHP library. When enabled, the
plugin sends page view and optional download events from your WordPress site
directly to a Matomo instance without loading Matomo’s JavaScript tracker.
Key benefits:
- Track page views on the server with full control over attributes such as title, URL and referrer.
- Optional download tracking rewrites file links and records the click before redirecting visitors.
- Optional AI assistant bot tracking detects crawls from ChatGPT, Claude, Perplexity and others and forwards them to Matomo’s dedicated AI Assistants report.
- Multisite aware – network admins can define defaults, individual sites can override them.
- Respects Do Not Track and Global Privacy Control headers through the underlying library.
- Logs issues to the WordPress debug log when
WP_DEBUGis enabled.
Looking for expert help with Matomo or server-side tracking? Pagemachine offers consulting, implementation and ongoing support via our Pagemetrics solution. More info: Pagemetrics.eu
Developer Hooks
Page view tracking:
pm_matomo_tracking_should_track_request— Returnfalseto skip page view tracking for the current request.
Download tracking:
pm_matomo_tracking_should_rewrite_downloads— Returnfalseto keep original download URLs for the current post.pm_matomo_tracking_is_download_url— Decide whether a specific URL should be rewritten (receives URL and default extension list).pm_matomo_tracking_download_extensions— Adjust the list of file extensions that count as downloads.pm_matomo_tracking_download_url— Customize the generated redirect URL used for download tracking.pm_matomo_tracking_download_redirect_status— Change the HTTP status code used when redirecting to the original file.
AI assistant bot tracking:
pm_matomo_tracking_ai_bot_user_agents— Extend or replace the list of User-Agent substrings used to detect AI bots.
General:
pm_matomo_tracking_log_message— Listen to debug messages emitted whileWP_DEBUGis enabled.
Example usages
// Skip tracking for administrators.
add_filter('pm_matomo_tracking_should_track_request', static function ($shouldTrack) {
return current_user_can('manage_options') ? false : $shouldTrack;
});
// Keep original download URLs on the privacy policy page.
add_filter('pm_matomo_tracking_should_rewrite_downloads', static function ($shouldRewrite) {
return is_page('privacy-policy') ? false : $shouldRewrite;
});
// Force CDN assets to be treated as downloads.
add_filter('pm_matomo_tracking_is_download_url', static function ($decision, $url) {
return str_contains($url, 'cdn.example.com/assets/') ? true : $decision;
}, 10, 2);
// Add extra file types to download tracking.
add_filter('pm_matomo_tracking_download_extensions', static function ($extensions) {
$extensions = array_merge($extensions, ['svg', 'heic']);
return array_unique($extensions);
});
// Append a checksum to rewritten download URLs.
add_filter('pm_matomo_tracking_download_url', static function ($trackingUrl, $target, $label) {
$checksum = substr(hash('sha256', $target . $label), 0, 12);
return add_query_arg('pm_checksum', $checksum, $trackingUrl);
}, 10, 3);
// Use a 307 redirect instead of the default 302.
add_filter('pm_matomo_tracking_download_redirect_status', static function () {
return 307;
});
// Add a custom bot to AI assistant tracking.
add_filter('pm_matomo_tracking_ai_bot_user_agents', static function (array $substrings): array {
$substrings[] = 'MyCustomBot';
return $substrings;
});
// Forward debug messages to the PHP error log while developing.
add_action('pm_matomo_tracking_log_message', static function ($level, $message) {
if (!defined('WP_DEBUG') || WP_DEBUG !== true) {
return;
}
// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
error_log(sprintf('[Pagemetrics for Matomo][%s] %s', strtoupper((string) $level), $message));
}, 10, 2);