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.

eu

Developer Hooks

Page view tracking:

• pm_matomo_tracking_should_track_request — Return false to skip page view tracking for the current request.

• pm_matomo_tracking_visitor_ip — Override the visitor IP forwarded to Matomo as cip (defaults to REMOTE_ADDR; used for page views and downloads when an auth token is set). Return an empty string to skip IP forwarding.

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. 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; });

// Behind a reverse proxy: forward the real client IP from X-Forwarded-For. add_filter('pm_matomo_tracking_visitor_ip', static function ($ip, $request) { $forwarded = $request->getHeaderLine('X-Forwarded-For'); if ($forwarded === '') { return $ip; }

// Use the first (client) address in the list. return trim(explode(',', $forwarded)[0]); }, 10, 2);

// Forward debug messages to the PHP error log while developing. == true) { return; }

error_log_error_log error_log(sprintf('[Pagemetrics for Matomo][%s] %s', strtoupper((string) $level), $message)); }, 10, 2);