What are the requirements for Matomo for WordPress?

You need at least WordPress 4.8 and PHP 7 as well as a MySQL database ideally running MySQL 5.1 or newer. We recommend having at least 128MB memory configured. If you have a high traffic website you may require more memory.

  • If you have WP_DEBUG enabled, then some notices re MySQL might appear which can be ignored.
  • If you have configured a custom content directory using WP_CONTENT_DIR or are using symlinks, then parts of the plugin likely won’t work (eg the Matomo Reporting/Admin/Tag Manager pages). You may be able to workaround this by specifying an environment variable (eg through apache or nginx) named MATOMO_WP_ROOT_PATH which points to the root directory of your WordPress directory. This directory should contain the file wp-load.php.
  • There may be an issue if you are using an incompatible plugin

A note on performance:
Running an analytics tool within your WordPress basically causes your server to receive an extra request for each page view. If your server is already on it’s limit in terms of CPU/LOAD, then you may want to consider installing Matomo on a separate server using Matomo On-Premise, or sign up for a Matomo Cloud account where we do the hosting for you, or ask your hoster to upgrade your server.

What are the differences between Matomo On-Premise and Matomo for WordPress?

  • There are no users and no website management in Matomo itself. Instead users and websites are managed in WordPress. This way you only need to manage your users and sites in one place. You can still give multiple users access to your reports, you simply don’t manage them in Matomo but instead in WordPress.
  • Matomo HTTP API is not available, we recommend you use the WordPress REST API instead
  • Widgets cannot be exported, we provide shortcodes to embed reports into your website instead
  • Tag Manager is not available in WP Multisite
  • Matomo CLI tools (console) may not work in WP Multisite
  • The entire login/logout and authentication is all done through WordPress. Therefore our login plugins like LoginSaml, Login HTTP Auth, etc. won’t work.
  • Individual Matomo core plugins cannot be disabled
  • The Matomo mobile app for Android and iOS won’t work with Matomo for WordPress
  • No custom logo can be uploaded in Matomo for WordPress
  • Matomo for WordPress focuses on simplicity by doing a lot of the work you usually have to do in On-Premise, for you. For example it automatically configures Geolocation and you don’t need to set up any cronjob to generate reports.

Why are there two different Matomo for WordPress plugins? What is the difference to WP Matomo Integration plugin?

WP-Matomo (WP-Piwik) plugin is an awesome plugin to connect your existing Matomo On-Premise or Matomo Cloud account with WordPress. The difference is that Matomo On-Premise for WordPress installs Matomo Analytics fully in your WordPress. So you get the convenience of having a powerful analytics platform within your WordPress.

If you are already using Matomo on our Cloud or On-Premise, we’d still highly recommend you use WP-Matomo. So that you get an easier way of inserting the tracking code into your WordPress site and get insights faster.

I have a high traffic website, will it be an issue to use Matomo for WordPress?

If you have a lot of traffic, we’d advise you to install Matomo On-Premise separately and use it in combination with our WordPress integration plugin WP-Matomo. There’s no specific traffic threshold we can give you on when it’s better to use Matomo On-Premise. It really depends on your server. We also need to await feedback from this beta test.

We reckon if you have more than 500,000 page views a month, you may want to think about using Matomo On-Premise with WP-Matomo instead, but this is just an estimate. In general, if the load on your server is already quite high, then it might be better to install Matomo on a separate server. See also recommended server sizing for running Matomo.

Which plugins is Matomo for WordPress known to be not compatible with?

Note: This list applies to Matomo On-Premise for WordPress, it does not apply to WP-Matomo Integration.

Does it support WP MultiSite?

Yes it does. When you have a MultiSite running, each blog has its own Matomo installation. In the network admin you can manage the tracking code for all sites in one convenient place.

If you have a lot of sites – or a lot of traffic in your WordPress – we recommend you install Matomo On-Premise as it’ll be much faster and easier for you to maintain. This option still gives you the ability to White Label, whereas, Matomo on WordPress doesn’t.

How do I use the API in Matomo for WordPress?

Matomo for WordPress doesn’t support our HTTP API but instead supports the WordPress REST API. View the reference and more information on our developer site. You can use it to automatically create goals, fetch reports, add annotations, and more.

Do Matomo Premium Features work with Matomo for WordPress?

Most of them do. This means features like Heatmaps, Session Recordings, Form Analytics, Media Analytics, Custom Reports and many more are available for WordPress. Only a few premium features like “A/B Testing”, “White Label”, and “Roll Up Reporting” are currently not available on Matomo for WordPress.

How do I disable the Tag Manager in Matomo for WordPress?

If you don’t want to use the Matomo Tag Manager and prefer to disable it, you need to add below code to your wp-config.php file:

define('MATOMO_DISABLE_TAG_MANAGER', true);

How do I migrate all my data from Matomo for WordPress to Matomo On-Premise?

This should work using our Migration plugin. You can install this plugin on your WordPress instance. Afterwards you can for example run the command like this:

php wp-content/plugins/matomo/app/console migration:measurable --source-idsite=1  --target-db-host=192.168.1.1 --target-db-username=root --target-db-password=secure --target-db-name=matomo2

In most cases the source-idsite should be 1. You can find the correct value in the Matomo for WordPress system report under the “Matomo Blog idSite” setting.

How do I install a Matomo Marketplace plugin in Matomo for WordPress

You can install and updates for plugins from our Marketplace using the “Matomo-Marketplace for WordPress plugin” which you can download here.

Once you have downloaded the zip file, please log into your WordPress and click on “Plugins => Add new”. There you will be able to upload the zip file and activate the plugin. Alternatively, you can unzip the file and copy the files manually into your wp-content/plugins directory.

The plugin will hook into the existing “Matomo Analytics => Marketplace” link in your WordPress and add two new tabs:

  • One to install and update plugins from our Matomo Marketplace with the convenience of a click
  • One to configure the license key in case you have purchased any Premium Features so you can install & update these with the easy of a click too

How do I delete or reset the Matomo for WordPress data completely?

If you need to remove all Matomo data including all tracked data, reports, and configurations, etc., you need to add below code to your wp-config.php file:

define('MATOMO_REMOVE_ALL_DATA', true);

Afterwards you can simply deactivate and delete the plugin in the WordPress plugin manager. It will delete all data and files related to Matomo.

How do I manually delete or reset all Matomo for WordPress data?

There are three ways to completely delete all data Matomo has stored in your WordPress database and filesystem.

1. Using WP-CLI

If you have WP-CLI installed, and the Matomo plugin is still installed in your WordPress, then you can simply run this command:

wp matomo uninstall --force

Please note that you maybe want to run the plugin uninstall command afterwards as otherwise Matomo may be reset/reinstalled again immediately.

wp plugin deactivate --uninstall matomo

2. Reactivating the plugin

Enable the removing of all data as described in this FAQ and then activate the plugin again in your WordPress if possible. Then you can deactivate and uninstall the plugin in the WordPress plugins manager and all data should be gone.

3. Manually delete all data:

Follow these steps to delete the data manually:

  • Delete all tables that include matomo after the WordPress table prefix $WPTABLEPREFIX_matomo_*, for example drop all tables where the name is like wp_matomo_*
  • Delete all options from the wp_options table whose value starts with matomo%. For example using this query: delete from wp_options where option_name like 'matomo%'
  • Delete the wp-content/uploads/matomo directory
  • Delete the wp-content/cache/matomo directory if it exists

Multisite

If you are using WP-MultiSite, then you also need to delete data from the wp_sitemeta table like this: delete from wp_sitemeta where meta_key like 'matomo%'

You will also need to remove the matomo folder within the uploads directory of each site. For example if the upload directories are stored in wp-content/uploads/sites/$BLOG_ID/ then you can run

rm -rf wp-content/uploads/sites/*/matomo

This should remove most, if not all of the data that Matomo stores in your WordPress DB and folder.

I have a high traffic website, how do I disable automatic execution of DB upgrades?

When you update any Matomo related plugins, we will automatically execute all upgrades these updates come with, such as:

  • New Plugin activations
  • Old plugin deactivations
  • DB schema changes
  • etc

Most DB schema changes are very fast except for major Matomo updates (version increases from say 3.0 to 4.0 or from 4.0 to 5.0). If you are using Matomo for WordPress with a high traffic website, these updates can take much longer than usual. For high traffic websites we recommend executing these upgrades on the command line. You can disable the auto upgrade after a Matomo plugin has been updated by adding this line to your wp-config.php:

define ( 'MATOMO_ENABLE_AUTO_UPGRADE', false );

You can then execute the update on the command line using this command

wp matomo update --force  (uses the WP-CLI)

If for some reason the WP CLI doesn’t work for you, you can also run our console command:

./wp-content/plugins/matomo/app/console core:update --yes

This will only work though when you are not in MultiSite and we recommend enabling the auto upgrade again after the update has been executed in case you are using our console tool.

I have an issue with the plugin, how do I troubleshoot and enable debug mode?

When you’re having issues with the plugin, we are happy to help and troubleshoot the issue. To help us troubleshoot your issue, we need you to enable the debug mode (WP_DEBUG) in WordPress.

Enable debugging

To enable debugging, please edit wp-config.php file and add the following line:

 define( 'WP_DEBUG', true );

By default, the errors and warnings will be shown within the HTML pages (the other constant WP_DEBUG_DISPLAY is set to true by default). You can also choose to save all errors to a debug.log file inside the /wp-content/ directory, by adding the following line:

define( 'WP_DEBUG_LOG', true );

Learn more on the WP_DEBUG WordPress.org page.

Get and copy the system report

In WordPress, go to the Admin panel, and under “Matomo Analytics”, click on “System report”.

Click the button “Copy system report” to copy the report to your clipboard.

Note: if you can’t even install the plugin at all, please update your wp-config.php file, and add the following line:

define( 'MATOMO_SAFE_MODE', true );

This will help making sure that the Matomo System report works even if you can’t install the plugin.

Archiving and reports not working?

To check if Archiving works in general please go to Matomo Analytics => System Report => Troubleshooting.

Click on the “Archive reports” button.

If WP_DEBUG is enabled, an error might be displayed. Or if archiving works, it may indicate an issue related to the WordPress cron (to troubleshoot the WordPress cron, we recommend to install the WP Control WordPress plugin and check under Tools when the next cron will be executed).

Create an issue on Github and paste the System report

Next step is to create an issue in our Matomo for WordPress issue tracker. In the issue description, you can describe your issue in as many details as possible and then paste the System Report, as well as any error or warning messages.

Then disable debug mode again

Once you are done with troubleshooting, edit wp-config.php file and set the constant to false:

 define( 'WP_DEBUG', false );

How do I prevent the Geo IP database from being downloaded into multiple directories in Matomo for WordPress when using MultiSite mode?

By default, Matomo will download and use the Geo IP DB only once for all your blogs instead of doing this for each blog. This works fine in almost every case unless you customise various parts in your Matomo such as the upload path and the directory structure etc. In this case, you can force Matomo to use a specific upload path by defining the following constant in your wp-config.php:

define('MATOMO_GLOBAL_UPLOAD_DIR', '/path/to/network/upload/directory');

This would be needed only if you are using WP MultiSite, e.g. if you are overwriting the upload path through some custom plugin.

I want to extend the WordPress plugin, where is the documentation?

We cannot wait to see what you, the community, will come up with!

We will make the documentation available closer to the release date on our Matomo Developer Zone. We’re already providing a few filters to hook into our plugin and you can also access Matomo data within any WordPress plugin.

There are so many awesome ways to make this work and to figure out how the insights could be better integrated into WordPress, so please let us know your ideas, and keep an eye out!

Where do I find the source code for the Matomo for WordPress plugin?

You can find the source code for both our WordPress plugins on GitHub:

How do I migrate all my data from Matomo for WordPress to the Matomo Cloud?

Simply get in touch with us and we will send you all the instructions for this.

How do I migrate all my data from Matomo On-Premise to Matomo for WordPress?

This is currently not supported / tested as we do not recommend doing this. Matomo On-Premise will run faster and you can have Matomo On-Premise for performance reasons on a separate server if needed. You will have a lot more options, plugins, etc available. We strongly recommend you stay with Matomo On-Premise if possible.

My WP-Cron is not working, how do I enable browser archiving?

We only recommend doing this if you have little traffic and generating reports for your Matomo is fast. Generating the reports on demand when you view them will make your Matomo slow otherwise. If for some reason you want to enable the browser archiving, for example because you are a developer or because you are having other issues, you can enable this feature by adding the following line to your wp-config.php:

define('MATOMO_TRIGGER_BROWSER_ARCHIVING', true)

Does Matomo for WordPress run on WordPress.com?

We don’t think so. As mentioned on the incompatible plugins guide, WordPress has found that SQL-heavy plugins can put a high strain on their servers and we reckon this plugin will fall into this category.

How can I configure the tracking code manually when I have WordPress network enabled in MultiSite mode?

This applies only if you have Matomo for WordPress network enabled in MultiSite and you want to configure the tracking code manually. As the tracking code is saved for the network and will be used across all blogs, you need to use variables in the tracking code which will be replaced with the actual values on demand:

  • {MATOMO_IDSITE} – will be replaced eg with 1
  • {MATOMO_API_ENDPOINT} – will be replaced eg with https://example.com/wp-content/plugins/matomo/app/matomo.php
  • {MATOMO_JS_ENDPOINT} – will be replaced eg with https://example.com/wp-content/uploads/matomo/matomo.js

Here’s an example:

<!-- Matomo -->
<script type="text/javascript">
var _paq = window._paq || [];
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
_paq.push(['setTrackerUrl', {MATOMO_API_ENDPOINT}]);
_paq.push(['setSiteId', '{MATOMO_IDSITE}']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.type='text/javascript'; g.async=true; g.defer=true; 
g.src={MATOMO_JS_ENDPOINT}; 
s.parentNode.insertBefore(g,s);
</script>
<!-- End Matomo Code -->