Pagemetrics for Matomo

Beschreibung

Pagemetrics for Matomo bringt datenschutzfreundliche, serverseitige Analysen nach WordPress und nutzt dafür die PHP-Bibliothek pagemachine/matomo-tracking. Aktiviert sendet das Plugin Seitenaufrufe und optionale Download-Ereignisse von deiner WordPress-Website direkt an eine Matomo-Instanz, ohne den JavaScript-Tracker von Matomo zu laden.

Wichtigste Vorteile:

• Erfasse Seitenaufrufe serverseitig mit voller Kontrolle über Attribute wie Titel, URL und Referrer.
• Optionales Download-Tracking schreibt Dateilinks um und protokolliert den Klick, bevor Besucher weitergeleitet werden.
• Optional AI assistant bot tracking detects crawls from ChatGPT, Claude, Perplexity and others and forwards them to Matomo’s dedicated AI Assistants report.
• Multisite-fähig – Netzwerk-Admins können Standardwerte definieren, einzelne Websites können sie überschreiben.
• Respektiert Do-Not-Track- und Global-Privacy-Control-Header über die zugrunde liegende Bibliothek.
• Protokolliert Probleme im WordPress-Debug-Log, wenn WP_DEBUG aktiv ist.

Du brauchst Unterstützung bei Matomo oder serverseitigem Tracking? Pagemachine bietet Beratung, Implementierung und fortlaufenden Support über unsere Pagemetrics-Lösung. Mehr Infos: Pagemetrics.eu

Entwickler-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 — Gib false zurück, um die originalen Download-URLs für den aktuellen Beitrag zu behalten.
• pm_matomo_tracking_is_download_url — Entscheide, ob eine bestimmte URL umgeschrieben werden soll (erhält URL und Standard-Endungsliste).
• pm_matomo_tracking_download_extensions — Passe die Liste der Dateiendungen an, die als Downloads zählen.
• pm_matomo_tracking_download_url — Passe die erzeugte Weiterleitungs-URL fürs Download-Tracking an.
• pm_matomo_tracking_download_redirect_status — Ändere den HTTP-Statuscode, der beim Weiterleiten zur Originaldatei genutzt wird.

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 — Lausche auf Debug-Meldungen, die ausgegeben werden, solange WP_DEBUG aktiv ist.

Beispiele

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