Title: Pagemetrics for Matomo Author: Pagemachine Published: November 18, 2025 Last modified: August 22, 2026 --- Search plugins ![](https://ps.w.org/pagemetrics-for-matomo/assets/banner-772x250.png?rev=3416370) ![](https://ps.w.org/pagemetrics-for-matomo/assets/icon.svg?rev=3416370) # Pagemetrics for Matomo By [Pagemachine](https://profiles.wordpress.org/pagemachine/) [Download](https://downloads.wordpress.org/plugin/pagemetrics-for-matomo.1.1.2.zip) * [Details](https://srd.wordpress.org/plugins/pagemetrics-for-matomo/#description) * [Reviews](https://srd.wordpress.org/plugins/pagemetrics-for-matomo/#reviews) * [Installation](https://srd.wordpress.org/plugins/pagemetrics-for-matomo/#installation) * [Development](https://srd.wordpress.org/plugins/pagemetrics-for-matomo/#developers) [Support](https://wordpress.org/support/plugin/pagemetrics-for-matomo/) ## Description 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](https://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); ``` ## Screenshots [⌊Pagemetrics for Matomo settings⌉⌊Pagemetrics for Matomo settings⌉[ Pagemetrics for Matomo settings ## Installation 1. Upload the `pagemetrics-for-matomo` plugin directory (including the bundled `vendor/` folder) to your site’s `wp-content/plugins` path. 2. Activate the plugin through the **Plugins Pagemetrics for Matomo** screen in WordPress. 3. Open **Settings Pagemetrics for Matomo** and configure: 4. * Matomo URL (e.g. `https://matomo.example.com/`) * Default Matomo site ID * Optional auth token (required for IP tracking and other privileged attributes) * HTTP timeout for Matomo requests * Download tracking toggle, if you want the plugin to rewrite file links automatically * AI assistant bot tracking toggle, to send AI crawler hits to Matomo’s AI Assistants report (requires Matomo 5.8.0 or later) 5. (Multisite) Network administrators can define defaults under **Network Admin Settings Pagemetrics for Matomo**. Individual sites can override those values on their local settings page. The plugin starts sending data as soon as the Matomo URL and site ID are set. ## FAQ ### Do I need to share my Matomo auth token? No. The auth token is optional. Provide it only if you need to forward visitor IP addresses or rely on Matomo parameters that require authentication. The token is stored server-side and never exposed to browsers. ### How is the visitor IP forwarded behind a proxy or CDN? When an auth token is set, the plugin forwards the visitor IP to Matomo as the cip parameter, resolved from `REMOTE_ADDR` by default. If your site is behind a reverse proxy or CDN, use the `pm_matomo_tracking_visitor_ip` filter to return the real client IP from your trusted forwarded header. ### Can I disable download link rewriting? Yes. Leave the _Track downloads_ toggle unchecked in the settings page. You can also use the `pm_matomo_tracking_should_rewrite_downloads` filter to disable rewriting programmatically for specific posts or file types. ### How does AI assistant bot tracking work? When the _Track AI assistant bots_ toggle is enabled, the plugin inspects the User- Agent header of every front-end request. If it matches a known AI crawler (ChatGPT, Claude, Perplexity, MistralAI, Gemini, GoogleAgent, NovaAct), a server-side telemetry hit is sent to Matomo using `recMode=1`. The hit is recorded in Matomo’s dedicated AI Assistants report and does not count as a normal visit. Requires Matomo 5.8.0 or later. ### Can I add custom AI bot User-Agents? Yes. Use the `pm_matomo_tracking_ai_bot_user_agents` filter to extend or replace the default list of User-Agent substrings: ``` add_filter('pm_matomo_tracking_ai_bot_user_agents', static function (array $substrings): array { $substrings[] = 'MyCustomBot'; return $substrings; }); ``` ### What happens if Matomo is down? Requests use a configurable HTTP timeout (default three seconds). When Matomo is unreachable, tracking is skipped and a warning is logged (only when WP_DEBUG is enabled). Page rendering continues normally. ## Reviews There are no reviews for this plugin. ## Contributors & Developers “Pagemetrics for Matomo” is open source software. The following people have contributed to this plugin. Contributors * [ Pagemachine ](https://profiles.wordpress.org/pagemachine/) * [ Mauricio Altamirano ](https://profiles.wordpress.org/maltamirano/) “Pagemetrics for Matomo” has been translated into 1 locale. Thank you to [the translators](https://translate.wordpress.org/projects/wp-plugins/pagemetrics-for-matomo/contributors) for their contributions. [Translate “Pagemetrics for Matomo” into your language.](https://translate.wordpress.org/projects/wp-plugins/pagemetrics-for-matomo) ### Interested in development? [Browse the code](https://plugins.trac.wordpress.org/browser/pagemetrics-for-matomo/), check out the [SVN repository](https://plugins.svn.wordpress.org/pagemetrics-for-matomo/), or subscribe to the [development log](https://plugins.trac.wordpress.org/log/pagemetrics-for-matomo/) by [RSS](https://plugins.trac.wordpress.org/log/pagemetrics-for-matomo/?limit=100&mode=stop_on_copy&format=rss). ## Changelog #### 1.1.2 * Tested with WordPress 7.1. * No functional changes. #### 1.1.1 * Fixed: the real visitor IP is now forwarded to Matomo as the `cip` parameter when an auth token is set, so page views and downloads geolocate the visitor instead of the WordPress server. * New `pm_matomo_tracking_visitor_ip` filter to override the forwarded IP (e.g. from a trusted proxy header) or disable IP forwarding. #### 1.1.0 * Added AI assistant bot tracking: detects crawls from ChatGPT, Claude, Perplexity and other AI agents and forwards them to Matomo’s AI Assistants report (requires Matomo 5.8.0+). * New `pm_matomo_tracking_ai_bot_user_agents` filter to extend the list of detected bot User-Agents. #### 1.0.0 * Initial release with server-side page view tracking, optional download tracking and multisite support. ## Meta * Version **1.1.2** * Last updated **2 months ago** * Active installations **Fewer than 10** * WordPress version ** 6.1 or higher ** * Tested up to **7.1.3** * PHP version ** 8.1 or higher ** * Languages * [English (US)](https://wordpress.org/plugins/pagemetrics-for-matomo/) and [German](https://de.wordpress.org/plugins/pagemetrics-for-matomo/). * [Translate into your language](https://translate.wordpress.org/projects/wp-plugins/pagemetrics-for-matomo) * Tags * [analytics](https://srd.wordpress.org/plugins/tags/analytics/)[matomo](https://srd.wordpress.org/plugins/tags/matomo/) [privacy](https://srd.wordpress.org/plugins/tags/privacy/)[server side](https://srd.wordpress.org/plugins/tags/server-side/) [tracking](https://srd.wordpress.org/plugins/tags/tracking/) * [Advanced View](https://srd.wordpress.org/plugins/pagemetrics-for-matomo/advanced/) ## Ratings No reviews have been submitted yet. [Your review](https://wordpress.org/support/plugin/pagemetrics-for-matomo/reviews/#new-post) [See all reviews](https://wordpress.org/support/plugin/pagemetrics-for-matomo/reviews/) ## Contributors * [ Pagemachine ](https://profiles.wordpress.org/pagemachine/) * [ Mauricio Altamirano ](https://profiles.wordpress.org/maltamirano/) ## Support Issues resolved in last two months: 1 out of 1 [View support forum](https://wordpress.org/support/plugin/pagemetrics-for-matomo/)