How to Install the Drupal Matomo Module

The Matomo Analytics Drupal module connects your Drupal site to your Matomo Analytics application and eases the process of modifying the tracking code to better suit your needs without advanced programming experience. The Drupal Matomo module tracking options include:

• Specifying Drupal blog entries to track
• Ignoring logged in users while working on web design and development tasks
• Tracking clicks for download links
• Respecting Do-Not-Track (DNT) web browser settings
• And much more

Using the right on-site web analytics software for your needs will prove to be a valuable tool for better understanding how online users interact with your website. This information can assist you with many on-going tasks to refine your branding such as sales funneling initiatives and content marketing ideas.

Below we’ll cover how to:

• Install the Matomo Drupal Integration Module
• Configure the Matomo Drupal Module
  • General Settings
  • Tracking Scope
  • Fix the Validation Error
  • Fix the ModSecurity 406 Error
• Add Additional Matomo Features in Drupal

Ignite your online presence with cutting-edge Drupal Website Hosting. Elevate speed, security, and reliability for a seamless website experience.

Install the Matomo Drupal Integration Module

1. Log into Drupal.
2. Install the Drupal module using the Matomo Analytics download link.
3. Click Enable newly added modules.
4. Under Statistics, check the box beside Matomo Analytics.
5. At the bottom, select Install.

Configure the Matomo Drupal Module

Below we’ll cover the two main module sections – General Settings and Tracking Scope.

General Settings

These settings create the basic Matomo tracking code to log user interaction.

1. Click Configuration at the top.
2. Under System, click Matomo Analytics.
3. Type the Matomo site ID number assigned from your Matomo application.
4. Add your Matomo HTTP URL. Use “HTTPS” if your Matomo application forces an SSL connection by default. If not, we recommend forcing an SSL connection in Matomo.
5. Add the Matomo HTTPS URL.
   
   To accept default tracking code settings, skip to the bottom of the module settings and Save configuration. We recommend you continue below.

Tracking Scope

Here you can configure how user behavior is collected.

The default Domains selection is “A single domain.” If you have subdomains under your Drupal directory, select “One domain with multiple subdomains.”

The Pages tab tracks all pages except the listed ones by default. Alternatively, you can select The listed pages only to track specific pages.

Roles in Drupal aren’t tracked by default, which ensures your analytics reports aren’t affected by administrative tasks. Select a checkbox to add tracking for specific roles. Or select “Add to every role except the selected ones” and select user roles to ignore.

Users are tracked by default but can opt-in or out if permissions are set. Track User ID to better track users across multiple devices.

The Page titles hierarchy feature affects your user experience (UX) in Matomo. The preset option is to Hide home page from hierarchy. You can deselect this if you wish. You can also Show page titles as hierarchy like breadcrumbs to show the page SEO title tags.

Links and downloads for mailto hyperlinks and most commonly used file extensions are tracked by default – docx, mp3, mp4, png, etc. You can add extensions to this text field with regular expressions.

Messages for statuses, warnings, and errors can be enabled here.

Search queries can be tracked to better understand what users are looking for while on your site.

The Matomo module respects Universal web tracking opt-out (Do-Not-Track) by default in the Privacy tab. You can also disable cookies from being stored in web browsers.

Developers can create Custom Variables and Custom JavaScript code for more customized analytics reporting.

Once you’re done configuring your Matomo tracking code, select Save configuration at the bottom. At the top you should see “The configuration options have been saved.” If not, check out the troubleshooting sections below.

If you’ve configured your caching settings, you may need to clear your Drupal cache for the tracking code to take effect immediately.

Fix the Validation Error

If you get the following error, change the Matomo HTTP URL at the top to “https://”:

The validation of “http://your-matomo.com/matomo.php” failed with an exception “cURL error 7: Failed to connect to your-matomo-site.com port 80: No route to host (see https://curl.haxx.se/libcurl/c/libcurl-errors.html)” (HTTP code 0).

Fix the ModSecurity 406 Error

If you get a 406 error at the top of the page when trying to update settings, and are on a VPS/dedicated server, you’ll need to check your web server error log (e.g. /etc/apache2/error_log) to figure out which ModSecurity rule ID is blocking the request.

If you’ve installed OWASP ModSecurity Core Rule Set (modsec2-rules-owasp-crs) in EasyApache 4, you may need additional whitelist rules.

1. Log into SSH or WebHost Manager (WHM) Terminal as user root.
2. Check the web server error log for the ModSec rule. For cPanel and CentOS systems:

   cat /var/log/apache2/error_log | grep /matomo.php

3. The ModSec error should resemble the following:
   [Tue Dec 15 12:15:57.969341 2020] [:error] [pid 5678:tid 12345678909876] [client 1.2.3.4:12345] [client 1.2.3.4] ModSecurity: Access denied with code 406 (phase 2). [file "/etc/apache2/conf.d/imh-modsec/rules.conf"] [line "99"] [id "112233"] [msg "Request Indicates an automated program explored the site"] [severity "NOTICE"] [hostname "example.com"] [uri "/matomo/matomo.php"] [unique_id "Y1oeBLwPZsbnx3eegjapijaKJQL"]
   
   Note the file path, uri, and id number for later. You can use the line indicator to view the actual rule within the ModSec configuration file.
4. There are two ways to resolve this 406 error: disable the rule or whitelist the action. We recommend and will continue with whitelisting the action via URI. To start, edit your ModSec whitelist file in the same directory as the rule file above. In the command below, replace the file path with the file in your error log:

   nano /etc/apache2/conf.d/imh-modsec/00_whitelist.conf

5. Add the following three lines at the bottom of the file, replacing the URI and rule ID to match your error log.

   <LocationMatch "/matomo/matomo.php">  SecRuleRemoveById 112233  </LocationMatch>

6. Test your Apache configuration:

   apachectl -t

   You should receive Syntax OK.
7. Restart Apache:

   systemctl restart httpd

   Debian/Ubuntu:

   systemctl restart apache2

8. Try to save your tracking code settings in Drupal again.

Afterwards, you can log into Matomo Analytics to view reports.

Add Additional Matomo Features in Drupal

There are 2 other related Drupal modules you can install for your Matomo setup.

• Matomo Reports allows you to see basic analytics within your Drupal dashboard without needing to log into Matomo
• Matomo Noscript tracks users with JavaScript disabled via browser extensions (e.g. uBlock Origin, AdBlock, and NoScript)