{"id":258652,"date":"2025-11-18T09:50:14","date_gmt":"2025-11-18T09:50:14","guid":{"rendered":"https:\/\/wordpress.org\/plugins\/matomo-tracking\/"},"modified":"2026-03-30T14:19:00","modified_gmt":"2026-03-30T14:19:00","slug":"pagemetrics-for-matomo","status":"publish","type":"plugin","link":"https:\/\/pcd.wordpress.org\/plugins\/pagemetrics-for-matomo\/","author":7445836,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_crdt_document":"","version":"1.1.0","stable_tag":"1.1.0","tested":"6.8.5","requires":"6.1","requires_php":"8.1","requires_plugins":null,"header_name":"Pagemetrics for Matomo","header_author":"Pagemachine AG","header_description":"Server-side Matomo tracking integration for WordPress powered by pagemachine\/matomo-tracking.","assets_banners_color":"c8daff","last_updated":"2026-03-30 14:19:00","external_support_url":"","external_repository_url":"","donate_link":"","header_plugin_uri":"https:\/\/wordpress.org\/plugins\/pagemetrics-for-matomo\/","header_author_uri":"https:\/\/pagemachine.de","rating":0,"author_block_rating":0,"active_installs":0,"downloads":216,"num_ratings":0,"support_threads":0,"support_threads_resolved":0,"author_block_count":0,"sections":["description","installation","faq","changelog"],"tags":{"1.0.0":{"tag":"1.0.0","author":"PAGEmachine","date":"2025-11-18 10:01:26"},"1.1.0":{"tag":"1.1.0","author":"PAGEmachine","date":"2026-03-30 14:19:00"}},"upgrade_notice":[],"ratings":[],"assets_icons":{"icon.svg":{"filename":"icon.svg","revision":3416370,"resolution":false,"location":"assets","locale":false}},"assets_banners":{"banner-1544x500.png":{"filename":"banner-1544x500.png","revision":3416370,"resolution":"1544x500","location":"assets","locale":""},"banner-772x250.png":{"filename":"banner-772x250.png","revision":3416370,"resolution":"772x250","location":"assets","locale":""}},"assets_blueprints":{},"all_blocks":[],"tagged_versions":["1.0.0","1.1.0"],"block_files":[],"assets_screenshots":{"screenshot-1.png":{"filename":"screenshot-1.png","revision":3494700,"resolution":"1","location":"assets","locale":""}},"screenshots":{"1":"Pagemetrics for Matomo settings"},"jetpack_post_was_ever_published":false},"plugin_section":[],"plugin_tags":[232,151654,396,5926,550],"plugin_category":[36,54],"plugin_contributors":[247909,247908],"plugin_business_model":[],"class_list":["post-258652","plugin","type-plugin","status-publish","hentry","plugin_tags-analytics","plugin_tags-matomo","plugin_tags-privacy","plugin_tags-server-side","plugin_tags-tracking","plugin_category-analytics","plugin_category-security-and-spam-protection","plugin_contributors-maltamirano","plugin_contributors-pagemachine","plugin_committers-pagemachine"],"banners":{"banner":"https:\/\/ps.w.org\/pagemetrics-for-matomo\/assets\/banner-772x250.png?rev=3416370","banner_2x":"https:\/\/ps.w.org\/pagemetrics-for-matomo\/assets\/banner-1544x500.png?rev=3416370","banner_rtl":false,"banner_2x_rtl":false},"icons":{"svg":"https:\/\/ps.w.org\/pagemetrics-for-matomo\/assets\/icon.svg?rev=3416370","icon":"https:\/\/ps.w.org\/pagemetrics-for-matomo\/assets\/icon.svg?rev=3416370","icon_2x":false,"generated":false},"screenshots":[{"src":"https:\/\/ps.w.org\/pagemetrics-for-matomo\/assets\/screenshot-1.png?rev=3494700","caption":"Pagemetrics for Matomo settings"}],"raw_content":"<!--section=description-->\n<p>Pagemetrics for Matomo adds privacy-friendly, server-side analytics to WordPress by\nleveraging the <code>pagemachine\/matomo-tracking<\/code> PHP library. When enabled, the\nplugin sends page view and optional download events from your WordPress site\ndirectly to a Matomo instance without loading Matomo's JavaScript tracker.<\/p>\n\n<p>Key benefits:<\/p>\n\n<ul>\n<li>Track page views on the server with full control over attributes such as title, URL and referrer.<\/li>\n<li>Optional download tracking rewrites file links and records the click before redirecting visitors.<\/li>\n<li>Optional AI assistant bot tracking detects crawls from ChatGPT, Claude, Perplexity and others and forwards them to Matomo's dedicated AI Assistants report.<\/li>\n<li>Multisite aware \u2013 network admins can define defaults, individual sites can override them.<\/li>\n<li>Respects Do Not Track and Global Privacy Control headers through the underlying library.<\/li>\n<li>Logs issues to the WordPress debug log when <code>WP_DEBUG<\/code> is enabled.<\/li>\n<\/ul>\n\n<p>Looking for expert help with Matomo or server-side tracking? <strong>Pagemachine<\/strong> offers\nconsulting, implementation and ongoing support via our <strong>Pagemetrics<\/strong> solution.\nMore info: <a href=\"https:\/\/pagemetrics.eu\/\">Pagemetrics.eu<\/a><\/p>\n\n<h3>Developer Hooks<\/h3>\n\n<p>Page view tracking:<\/p>\n\n<ul>\n<li><code>pm_matomo_tracking_should_track_request<\/code> \u2014 Return <code>false<\/code> to skip page view tracking for the current request.<\/li>\n<\/ul>\n\n<p>Download tracking:<\/p>\n\n<ul>\n<li><code>pm_matomo_tracking_should_rewrite_downloads<\/code> \u2014 Return <code>false<\/code> to keep original download URLs for the current post.<\/li>\n<li><code>pm_matomo_tracking_is_download_url<\/code> \u2014 Decide whether a specific URL should be rewritten (receives URL and default extension list).<\/li>\n<li><code>pm_matomo_tracking_download_extensions<\/code> \u2014 Adjust the list of file extensions that count as downloads.<\/li>\n<li><code>pm_matomo_tracking_download_url<\/code> \u2014 Customize the generated redirect URL used for download tracking.<\/li>\n<li><code>pm_matomo_tracking_download_redirect_status<\/code> \u2014 Change the HTTP status code used when redirecting to the original file.<\/li>\n<\/ul>\n\n<p>AI assistant bot tracking:<\/p>\n\n<ul>\n<li><code>pm_matomo_tracking_ai_bot_user_agents<\/code> \u2014 Extend or replace the list of User-Agent substrings used to detect AI bots.<\/li>\n<\/ul>\n\n<p>General:<\/p>\n\n<ul>\n<li><code>pm_matomo_tracking_log_message<\/code> \u2014 Listen to debug messages emitted while <code>WP_DEBUG<\/code> is enabled.<\/li>\n<\/ul>\n\n<h3>Example usages<\/h3>\n\n<pre><code>\/\/ Skip tracking for administrators.\nadd_filter('pm_matomo_tracking_should_track_request', static function ($shouldTrack) {\n    return current_user_can('manage_options') ? false : $shouldTrack;\n});\n\n\/\/ Keep original download URLs on the privacy policy page.\nadd_filter('pm_matomo_tracking_should_rewrite_downloads', static function ($shouldRewrite) {\n    return is_page('privacy-policy') ? false : $shouldRewrite;\n});\n\n\/\/ Force CDN assets to be treated as downloads.\nadd_filter('pm_matomo_tracking_is_download_url', static function ($decision, $url) {\n    return str_contains($url, 'cdn.example.com\/assets\/') ? true : $decision;\n}, 10, 2);\n\n\/\/ Add extra file types to download tracking.\nadd_filter('pm_matomo_tracking_download_extensions', static function ($extensions) {\n    $extensions = array_merge($extensions, ['svg', 'heic']);\n    return array_unique($extensions);\n});\n\n\/\/ Append a checksum to rewritten download URLs.\nadd_filter('pm_matomo_tracking_download_url', static function ($trackingUrl, $target, $label) {\n    $checksum = substr(hash('sha256', $target . $label), 0, 12);\n    return add_query_arg('pm_checksum', $checksum, $trackingUrl);\n}, 10, 3);\n\n\/\/ Use a 307 redirect instead of the default 302.\nadd_filter('pm_matomo_tracking_download_redirect_status', static function () {\n    return 307;\n});\n\n\/\/ Add a custom bot to AI assistant tracking.\nadd_filter('pm_matomo_tracking_ai_bot_user_agents', static function (array $substrings): array {\n    $substrings[] = 'MyCustomBot';\n    return $substrings;\n});\n\n\/\/ Forward debug messages to the PHP error log while developing.\nadd_action('pm_matomo_tracking_log_message', static function ($level, $message) {\n    if (!defined('WP_DEBUG') || WP_DEBUG !== true) {\n        return;\n    }\n\n    \/\/ phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log\n    error_log(sprintf('[Pagemetrics for Matomo][%s] %s', strtoupper((string) $level), $message));\n}, 10, 2);\n<\/code><\/pre>\n\n<!--section=installation-->\n<ol>\n<li>Upload the <code>pagemetrics-for-matomo<\/code> plugin directory (including the bundled <code>vendor\/<\/code>\nfolder) to your site's <code>wp-content\/plugins<\/code> path.<\/li>\n<li>Activate the plugin through the <strong>Plugins \u2192 Pagemetrics for Matomo<\/strong> screen in WordPress.<\/li>\n<li>Open <strong>Settings \u2192 Pagemetrics for Matomo<\/strong> and configure:\n\n<ul>\n<li>Matomo URL (e.g. <code>https:\/\/matomo.example.com\/<\/code>)<\/li>\n<li>Default Matomo site ID<\/li>\n<li>Optional auth token (required for IP tracking and other privileged attributes)<\/li>\n<li>HTTP timeout for Matomo requests<\/li>\n<li>Download tracking toggle, if you want the plugin to rewrite file links automatically<\/li>\n<li>AI assistant bot tracking toggle, to send AI crawler hits to Matomo's AI Assistants report (requires Matomo 5.8.0 or later)<\/li>\n<\/ul><\/li>\n<li>(Multisite) Network administrators can define defaults under <strong>Network Admin \u2192 Settings \u2192 Pagemetrics for Matomo<\/strong>. Individual sites can override those values on their local settings page.<\/li>\n<\/ol>\n\n<p>The plugin starts sending data as soon as the Matomo URL and site ID are set.<\/p>\n\n<!--section=faq-->\n<dl>\n<dt id=\"do%20i%20need%20to%20share%20my%20matomo%20auth%20token%3F\"><h3>Do I need to share my Matomo auth token?<\/h3><\/dt>\n<dd><p>No. The auth token is optional. Provide it only if you need to forward visitor\nIP addresses or rely on Matomo parameters that require authentication. The\ntoken is stored server-side and never exposed to browsers.<\/p><\/dd>\n<dt id=\"can%20i%20disable%20download%20link%20rewriting%3F\"><h3>Can I disable download link rewriting?<\/h3><\/dt>\n<dd><p>Yes. Leave the <em>Track downloads<\/em> toggle unchecked in the settings page. You can\nalso use the <code>pm_matomo_tracking_should_rewrite_downloads<\/code> filter to disable\nrewriting programmatically for specific posts or file types.<\/p><\/dd>\n<dt id=\"how%20does%20ai%20assistant%20bot%20tracking%20work%3F\"><h3>How does AI assistant bot tracking work?<\/h3><\/dt>\n<dd><p>When the <em>Track AI assistant bots<\/em> toggle is enabled, the plugin inspects the\nUser-Agent header of every front-end request. If it matches a known AI crawler\n(ChatGPT, Claude, Perplexity, MistralAI, Gemini, GoogleAgent, NovaAct), a\nserver-side telemetry hit is sent to Matomo using <code>recMode=1<\/code>. The hit is\nrecorded in Matomo's dedicated AI Assistants report and does not count as a\nnormal visit. Requires Matomo 5.8.0 or later.<\/p><\/dd>\n<dt id=\"can%20i%20add%20custom%20ai%20bot%20user-agents%3F\"><h3>Can I add custom AI bot User-Agents?<\/h3><\/dt>\n<dd><p>Yes. Use the <code>pm_matomo_tracking_ai_bot_user_agents<\/code> filter to extend or replace\nthe default list of User-Agent substrings:<\/p>\n\n<pre><code>add_filter('pm_matomo_tracking_ai_bot_user_agents', static function (array $substrings): array {\n    $substrings[] = 'MyCustomBot';\n    return $substrings;\n});\n<\/code><\/pre><\/dd>\n<dt id=\"what%20happens%20if%20matomo%20is%20down%3F\"><h3>What happens if Matomo is down?<\/h3><\/dt>\n<dd><p>Requests use a configurable HTTP timeout (default three seconds). When Matomo\nis unreachable, tracking is skipped and a warning is logged (only when\n    WP_DEBUG is enabled). Page rendering continues normally.<\/p><\/dd>\n\n<\/dl>\n\n<!--section=changelog-->\n<h4>1.1.0<\/h4>\n\n<ul>\n<li>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+).<\/li>\n<li>New <code>pm_matomo_tracking_ai_bot_user_agents<\/code> filter to extend the list of detected bot User-Agents.<\/li>\n<\/ul>\n\n<h4>1.0.0<\/h4>\n\n<ul>\n<li>Initial release with server-side page view tracking, optional download tracking and multisite support.<\/li>\n<\/ul>","raw_excerpt":"Pagemetrics for Matomo adds server-side, privacy-friendly analytics to WordPress. It tracks page views, downloads, and AI assistant bot crawls without &hellip;","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin\/258652","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin"}],"about":[{"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/types\/plugin"}],"replies":[{"embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/comments?post=258652"}],"author":[{"embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wporg\/v1\/users\/pagemachine"}],"wp:attachment":[{"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/media?parent=258652"}],"wp:term":[{"taxonomy":"plugin_section","embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_section?post=258652"},{"taxonomy":"plugin_tags","embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_tags?post=258652"},{"taxonomy":"plugin_category","embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_category?post=258652"},{"taxonomy":"plugin_contributors","embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_contributors?post=258652"},{"taxonomy":"plugin_business_model","embeddable":true,"href":"https:\/\/pcd.wordpress.org\/plugins\/wp-json\/wp\/v2\/plugin_business_model?post=258652"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}