How to Install the Matomo Drupal 9 Integration 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 Matomo Drupal 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:

Get the power and performance you need without additional configurations with our Drupal VPS Hosting.

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.

Matomo Drupal module general settings
  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.”

Matomo Drupal module domains settings

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

Matomo Drupal module pages settings

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.

Matomo Drupal module roles settings

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.

Matomo Drupal module users settings

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.

Matomo Drupal module page titles hierarchy settings

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.

Matomo Drupal module links settings

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

Matomo Drupal module messages settings

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

Matomo Drupal module search settings

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.

Matomo Drupal module privacy settings

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)

Get the power and performance you need without additional configurations with our Drupal VPS Hosting.

J
Jacqueem Content Writer I

Technical writer focused on cybersecurity and musicianship.

More Articles by Jacqueem

Comments

It looks like this article doesn't have any comments yet - you can be the first. If you have any comments or questions, start the conversation!

Was this article helpful? Let us know!