Pagemetrics for Matomo

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_DEBUG is 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 — Return false to skip page view tracking for the current request.

Download tracking:

• pm_matomo_tracking_should_rewrite_downloads — Return false to 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 while WP_DEBUG is 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);