Pagemetrics for Matomo for WordPress Plugin Directory

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.

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

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