Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/openmost/openmost-site-kit

Matomo plugin for WordPress
https://github.com/openmost/openmost-site-kit

matomo wordpress wordpress-plugin

Last synced: about 1 month ago
JSON representation

Matomo plugin for WordPress

Awesome Lists containing this project

README 

          
=== Matomo Site Kit ===



Contributors: Openmost

Requires at least: 6.0

Tested up to: 6.9.1

Stable tag: 2.3.0

Tags: matomo, connect, analytics, tracking, ecommerce, gdpr, google analytics alternative, web analytics

Requires PHP: 8.2

License: GPL-2.0-or-later

License URI: https://www.gnu.org/licenses/gpl-2.0.html



The most complete Matomo Analytics plugin for WordPress. Server-side tracking, WooCommerce ecommerce, site search, GDPR compliance, and Tag Manager support.



== Description ==



**Matomo Site Kit** is the ultimate WordPress plugin for integrating [Matomo Analytics](https://matomo.org/) - the leading open-source, privacy-focused alternative to Google Analytics.



Whether you use Matomo Cloud or self-hosted Matomo On-Premise, this plugin provides everything you need for comprehensive website analytics while respecting your visitors' privacy.



= Why Choose Matomo Site Kit? =



* **Privacy-First Analytics** - Full GDPR, CCPA, and PECR compliance out of the box

* **No Data Sampling** - 100% accurate data, unlike Google Analytics

* **You Own Your Data** - No third-party data sharing

* **Ad-Blocker Resistant** - Server-side tracking bypasses most ad blockers

* **WooCommerce Ready** - Complete ecommerce tracking for your online store



= Three Powerful Tracking Methods =



Choose the tracking method that best fits your needs:



* **Classic JavaScript Tracking** - Traditional Matomo tracking with full feature support using `_paq.push()`. Best for most websites.



* **Matomo Tag Manager (MTM)** - Advanced tag management with dataLayer integration. Perfect for marketing teams who need flexible trigger and variable management.



* **Server-Side PHP Tracking** - Privacy-friendly tracking that works even when JavaScript is disabled or blocked. Ideal for GDPR-focused websites and bypassing ad blockers.



= Complete Feature List =



**Analytics Dashboard**

* Real-time analytics overview in WordPress admin

* Visits, page views, bounce rate, and session duration

* WordPress Dashboard widget for quick stats

* Per-post and per-page analytics metabox



**WooCommerce Ecommerce Tracking**

* Product view tracking with SKU, name, price, and categories

* Category page view tracking

* Add to cart and remove from cart events

* Cart update tracking

* Complete order tracking with revenue, tax, and shipping

* Works with all three tracking methods



**Site Search Tracking**

* Automatic WordPress search tracking

* Search keyword capture

* Category filter detection

* Search result count

* Zero configuration required



**Automatic Annotations**

* Create Matomo annotations when content is published

* Select which post types trigger annotations

* Customizable format with variables: {post_type}, {title}, {url}, {author}

* Live preview in settings



**Privacy & GDPR Compliance**

* Consent mode options (requireConsent, requireCookieConsent)

* Privacy opt-out shortcode [matomo_opt_out]

* Server-side tracking for cookieless analytics

* Exclude tracking by user role

* Compatible with cookie consent plugins



**Advanced Features**

* User ID tracking with SHA256 hashed email

* Heartbeat Timer for accurate time-on-page measurement

* DataLayer integration for Tag Manager (Matomo config + page context: page_type, post_type label, taxonomies, locale, login status, post_id)

* AI Bot Tracking - Track visits from AI assistants (ChatGPT, Perplexity, Claude, etc.) separately in Matomo (requires Matomo 5.7+)

* Bot detection and filtering

* Noscript fallback for JavaScript-disabled browsers

* DNS prefetch and script preloading for performance

* Matomo Cloud and On-Premise support



= Perfect For =



* **Bloggers** who want simple, privacy-respecting analytics

* **WooCommerce stores** needing detailed ecommerce insights

* **Agencies** managing multiple client websites

* **Enterprise** organizations with strict data privacy requirements

* **GDPR-conscious** website owners in the EU

* **Marketing teams** using Matomo Tag Manager



= Matomo Cloud vs On-Premise =



This plugin works seamlessly with both:



* **Matomo Cloud** - Hosted solution at matomo.cloud, no server management needed

* **Matomo On-Premise** - Self-hosted on your own server for complete data ownership



== Installation ==



= Automatic Installation =



1. Go to Plugins > Add New in your WordPress admin

2. Search for "Matomo Site Kit"

3. Click "Install Now" and then "Activate"

4. Go to Site Kit > Settings to configure



= Manual Installation =



1. Download the plugin ZIP file

2. Go to Plugins > Add New > Upload Plugin

3. Upload the ZIP file and click "Install Now"

4. Activate the plugin

5. Go to Site Kit > Settings to configure



= Configuration =



**Required for all tracking methods:**

* Matomo Host URL (e.g., https://analytics.example.com or https://yoursite.matomo.cloud)

* Site ID (found in Matomo under Administration > Websites)



**Additional requirements by tracking method:**



* **Classic JavaScript** - Host URL + Site ID

* **Matomo Tag Manager** - Host URL + Container ID

* **Server-Side PHP** - Host URL + Site ID + Auth Token



**For Dashboard & Annotations:**

* Auth Token (API key from Matomo under Administration > Personal > Security)



== Frequently Asked Questions ==



= Is Matomo Site Kit free? =



Yes, Matomo Site Kit is 100% free and open source. You can use it with either Matomo Cloud (paid hosting) or self-hosted Matomo On-Premise (free).



= Is Matomo GDPR compliant? =



Yes, Matomo is designed for privacy and can be configured for full GDPR compliance. With consent mode enabled, no tracking occurs until the visitor gives consent. Server-side tracking can even work without cookies.



= How is Matomo different from Google Analytics? =



Matomo is a privacy-focused alternative where you own 100% of your data. Unlike Google Analytics, Matomo doesn't sample data, doesn't share data with third parties, and can be self-hosted for complete control.



= Should I remove existing Matomo tracking code? =



Yes, Matomo Site Kit is an all-in-one solution. Remove any existing Matomo code from your theme or other plugins to avoid duplicate tracking.



= Which tracking method should I use? =



* **Classic JavaScript** - Best for most sites. Full feature support, easy setup.

* **Matomo Tag Manager** - Best for marketing teams who need advanced tag management, triggers, and variables.

* **Server-Side PHP** - Best for privacy-focused sites, GDPR compliance, or when ad blockers are a concern.



= Can I use multiple tracking methods together? =



Yes, you can combine Server-Side PHP with either Classic JS or Tag Manager. Server-side handles the initial page view reliably, while client-side handles interactive events like clicks and form submissions.



= Does WooCommerce tracking work with all methods? =



Yes, each tracking method has its own WooCommerce ecommerce toggle. Enable the one that matches your active tracking method for complete ecommerce analytics.



= How does Site Search tracking work? =



When a visitor searches your site, the plugin automatically tracks the search keyword, any category filters applied, and the number of results found. No configuration needed - it works out of the box with WordPress search.



= What is the annotation feature? =



Annotations are notes in Matomo that mark specific dates. This plugin can automatically create annotations when you publish content, helping you correlate traffic changes with content releases.



= What format should I use for annotations? =



The default format is: `New {post_type} published: "{title}"`



Available variables:

* {post_type} - Post type label (e.g., "Post", "Page", "Product")

* {title} - The post title

* {url} - The permalink URL

* {author} - The author's display name



= Will this slow down my website? =



No, the plugin is optimized for performance with DNS prefetch, script preloading, and async loading. Server-side tracking has zero impact on front-end performance.



= Does it work with caching plugins? =



Yes, Matomo Site Kit works with all major caching plugins including WP Rocket, W3 Total Cache, WP Super Cache, and LiteSpeed Cache.



= Does it work with page builders? =



Yes, the plugin works with all page builders including Elementor, Divi, Beaver Builder, WPBakery, and Gutenberg.



= How do I add the opt-out feature for GDPR? =



Add the shortcode `[matomo_opt_out]` to any page or post. This displays a Matomo opt-out form allowing visitors to opt out of tracking.



Shortcode options:

* `[matomo_opt_out language="en"]` - Set language

* `[matomo_opt_out show_intro="0"]` - Hide introduction text

* `[matomo_opt_out background_color="ffffff"]` - Custom background

* `[matomo_opt_out font_color="000000"]` - Custom text color



= Can I exclude certain users from tracking? =



Yes, go to Settings and select which user roles to exclude. Common choices are Administrator and Editor to avoid skewing analytics with your own visits.



= How do I track logged-in users? =



Enable "User ID Tracking" in the settings. The plugin will track logged-in users using a SHA256 hash of their email address, allowing you to see user journeys across devices while maintaining privacy.



= What is Heartbeat Timer? =



Heartbeat Timer sends periodic signals to Matomo while the page is open, providing more accurate "time on page" measurements. Without it, the time spent on the last page of a session cannot be measured.



= Does server-side tracking work with Matomo Cloud? =



Yes, server-side tracking works with both Matomo Cloud and On-Premise installations. You'll need your Auth Token for it to work.



= Why aren't my WooCommerce orders being tracked? =



Make sure you've enabled the ecommerce tracking option for your active tracking method. Each method (Classic, Tag Manager, Server-Side) has its own toggle.



= What is AI Bot Tracking? =



AI Bot Tracking allows you to track visits from AI assistants like ChatGPT, Perplexity, Claude, and Gemini separately in Matomo. Instead of discarding these visits, Matomo 5.7+ can record them in a dedicated bot tracking report. Enable this feature in Settings to see how AI agents interact with your content.



= Which AI bots are detected? =



The plugin detects user-triggered AI assistants including ChatGPT-User, GPTBot, PerplexityBot, ClaudeBot, Claude-Web, Google-Extended, Gemini, Meta-ExternalAgent, AmazonBot, AppleBot-Extended, OAI-SearchBot, and others. The list is regularly updated.



= Can I use this with other analytics plugins? =



While technically possible, we recommend using only Matomo Site Kit for analytics to avoid conflicts and duplicate tracking.



= Which dataLayer variables are pushed when I use Matomo Tag Manager? =



Two independent toggles control what is pushed to `_mtm`:



* **Push config context to dataLayer** - Pushes `matomo.host`, `matomo.site_id`, `matomo.container_id` and `wordpress.environment`. Used by MTM triggers that need to know which Matomo instance / environment the page runs on.

* **Push page context to dataLayer** - Pushes ready-to-use variables for page-level triggers: `page_type` (slug: home, blog, search, error_404, author, ``, `archive_`, `archive_`, `archive_date`, `archive`), `post_type` (singular human-readable label, e.g. "Article"), `post_id` on singular pages, taxonomy term names (`category`, `tag` or any custom taxonomy slug), `author` on author archives, `locale` (e.g. fr_FR), `user_login_status` ("logged_in" / "logged_out"), plus `user_id` (SHA256 hashed email) and `user_role` if User ID tracking is enabled.



Both toggles are independent - enable only what your MTM setup actually uses.



= How do I get support? =



For support, please visit our [GitHub repository](https://github.com/openmost/openmost-site-kit) or contact us through [openmost.io](https://openmost.io).



= How can I contribute? =



Contributions are welcome! Visit our [GitHub repository](https://github.com/openmost/openmost-site-kit) to report issues, suggest features, or submit pull requests.



== Screenshots ==



1. Dashboard

2. Settings - Tracking

3. Settings - Features

4. Settings - Privacy



== Changelog ==



= 2.3.0 =

Release date: 2026-04-16



**New Features:**



* Page context dataLayer - New optional toggle "Push page context to dataLayer" that enriches `_mtm` with ready-to-use variables for Tag Manager triggers and variables

* Pushed variables include: `page_type` (home, blog, search, error_404, author, ``, `archive_`, `archive_`, `archive_date`, `archive`), `post_type` (singular human-readable label), `post_id` on singular pages, taxonomies (`category`, `tag`, any custom taxonomy slug with term names), `author` on author archives, `locale`, and `user_login_status`

* `user_id` (SHA256) and `user_role` are now pushed in the page context when User ID tracking is enabled (previously in the Matomo config object)



**Improvements:**



* Renamed the Tag Manager "Push context to dataLayer" toggle to "Push config context to dataLayer" to clearly distinguish it from the new page context toggle

* Enabling the config context toggle now pre-checks the page context toggle

* Config context push now only carries `matomo.*` and `wordpress.environment` - keeps the initial payload minimal

* `matomo.site_id` is now pushed as an integer (was a string)

* Removed `recMode` from the dataLayer push (kept on the actual tracker requests where it is needed)

* Matomo Host is now trimmed and stripped of any trailing slash on save and in the dataLayer payload

* Custom taxonomies registered with `publicly_queryable` or `show_ui` (but not `public`) are now included



**Technical:**



* New helpers: `omsk_get_page_context()`, `omsk_get_post_type_label()`, `omsk_get_current_user_role()`

* REST settings add `enableMtmPageContext` flag (`omsk-matomo-enable-mtm-page-context-field` option)



= 2.2.0 =

Release date: 2026-03-06



**New Features:**



* AI Bot Tracking - Track visits from AI assistants (ChatGPT, Perplexity, Claude, Gemini, etc.) separately in Matomo using the bot tracking API (recMode). Requires Matomo 5.7.0+

* Server-Side PHP Tracking - Track page views server-side for ad-blocker resistance and enhanced privacy

* WooCommerce Ecommerce Tracking - Complete ecommerce analytics for all three tracking methods

* Site Search Tracking - Automatically track WordPress searches with keyword, category, and result count

* Automatic Annotations - Create Matomo annotations when posts are published

* Customizable annotation format with variables ({post_type}, {title}, {url}, {author})

* Privacy settings page with robots.txt and .well-known/ai-plugin.json management



**Improvements:**



* Restructured Settings page with intuitive tracking method cards

* Each tracking method now clearly shows its required fields

* Separated feature cards for better organization (GDPR, Heartbeat, User ID, Ecommerce, Search, AI Bot Tracking)

* Renamed Dashboard tab to Features tab for clarity

* Intelligent bot detection for server-side tracking with AI assistant categorization

* Server-side AI bot detection sends recMode=1 (bot-only) requests with source label

* Classic JS and Tag Manager use recMode=2 (auto mode) for automatic AI bot classification

* Noscript image tracker includes recMode=2 for pixel-based bot detection

* Privacy opt-out shortcode now uses modern script-based approach

* Full WordPress Coding Standards compliance

* Enhanced security with proper escaping and sanitization throughout

* Added REST API nonce for improved security

* Performance optimizations with DNS prefetch and script preloading



**Technical:**



* Complete code audit for security and best practices

* Improved internationalization (i18n) support

* PHP 8.2+ compatibility

* WordPress 6.0+ required

* Matomo 5.7.0+ required for AI Bot Tracking feature



= 2.1.1 =

Release date: 2025-11-24



* Tested on WordPress 6.9



= 2.1.0 =

Release date: 2025-11-24



* Refactored Settings page with tabbed interface

* Added Dashboard tab for API configuration

* Added User ID tracking feature (SHA256 hashed email)

* Added Heartbeat Timer option for classic tracking

* Improved Tag Manager dataLayer with wordpress.user_id

* Removed setup wizard in favor of streamlined settings

* Various UI/UX improvements

* Added noscript image tracker fallback



= 2.0.0 =

Release date: 2025-11-20



* Complete refactor using React and WordPress components

* New modern dashboard interface

* WordPress Dashboard widget

* Post/Page analytics metabox



= 1.1.2 =

Release date: 2024-09-25



* Fix missing function get_value()



= 1.1.0 =

Release date: 2023-06-29



* Add dataLayer sync

* Add Matomo details in dataLayer

* Fix Matomo Cloud instances support



= 1.0.2 =

Release date: 2023-06-27



* Support Matomo Cloud CDN in tracking codes



= 1.0.0 =

Release date: 2023-05-17



* Initial plugin release



== Upgrade Notice ==



= 2.3.0 =

New "Push page context to dataLayer" option for Tag Manager: adds page_type, post_type label, post_id, taxonomies, locale and login status to `_mtm`. Host URL is now auto-trimmed. User ID / role moved to the page context payload.



= 2.2.0 =

Major feature release! New AI bot tracking (Matomo 5.7+), server-side tracking, WooCommerce ecommerce, site search tracking, automatic annotations, and privacy settings. Includes security improvements and WordPress coding standards compliance. Recommended for all users.



= 2.1.0 =

New User ID tracking and Heartbeat Timer features. Improved settings interface.



= 2.0.0 =

Complete redesign with modern React interface. New dashboard widget and post analytics.