Integrate Consent Managers (CMP) with the Matomo Image tracker

This guide provides general technical implementation advice. It does not constitute legal advice. Consult with a qualified privacy professional to ensure full compliance with applicable laws.

Website owners are responsible for their website’s compliance with privacy laws. This includes responsibility for collecting and retaining a log of their visitors’ valid tracking consents where required.

A Consent Management Platform (CMP) is a tool that helps website owners ensure compliance with privacy laws by managing visitor consent for tracking. It presents website visitors with a consent banner explaining data processing activities and allows them to accept or decline specific purposes, such as analytics or marketing.

If you are using the Matomo Image tracker and your legal jurisdiction requires prior consent for analytics tracking, you will need to obtain consent from your website/app visitors before the tracking request is sent.

Unlike the standard JavaScript tracking code, the image tracker does not use cookies and does not support the Matomo consent features like requireConsent. Many Consent Management Platforms (CMPs) offer features to block or delay scripts before consent is given, which is a simple way to integrate consent before tracking.

However, the Matomo image tracker is plain HTML and most CMPs will not automatically block the <img> tag. You may need to modify the image tracking code, for example, by using attributes like data-src to prevent the tracker from loading until the visitor has provided consent.

This guide focuses on two integration methods using the Matomo Image tracker.

Each method is based on different regulatory requirements, so it is important to consider your organisation’s legal obligations and tracking needs:

  1. Consent-based Tracking: For websites targeting users in countries that require prior consent for the use of tracking technologies for analytics and marketing (for example, most or EU and EEA countries), enable Matomo tracking only after obtaining visitor consent.

  2. Opt-out Tracking for CNIL Exemption: For organisations relying on the CNIL consent exemption for website analytics, limited tracking is permitted, provided that conditions of exemption are strictly met and users are offered a clear opt-out mechanism. CNIL exemption is strict and if any conditions of the CNIL exemption are not met, consent is also required.

Note: If you’re using the image tracker as a fallback for users who have JavaScript disabled, make sure that your primary tracking method (e.g. the JavaScript tracker) is also correctly configured to respect user consent. Consent enforcement must be consistent across all tracking methods, not just the fallback. Refer to the Matomo Consent Manager Integration Guides on setting up consent using the Matomo JavaScript tracking code or Matomo Tag Manager.

Before you start

  1. Create your consent manager account.
  2. Complete the necessary steps to configure your consent banner in line with the consent method used and the legal requirements that apply to your website.
  3. To ensure that consent changes take effect immediately, you need to enable the auto page reload (or equivalent) setting in your CMP. This refreshes the page when a user revokes consent, and removes any previously allowed image tracker.
  4. Follow the consent manager instructions to add the consent manager script directly to your website’s code. The script must be placed as the first element inside the <head> tag on every webpage you want to track.

In regions with strict privacy and ePrivacy laws, e.g., most of the EU or UK, websites must obtain explicit consent before collecting analytics data. Consent-based tracking ensures that no pixel tracking occurs until a website visitor actively provides consent.

This tracking method is only activated after the visitor gives consent. When consent is revoked or denied, pixel tracking stops.

Install and modify the Image tracker code

  1. If you do not have the image tracker installed yet, go to your Matomo settings Settings Cog Icon > Measurables > Tracking Code and select the website you want to track.
  2. Copy the Image tracking code shown in the code box and modify it according to your CMP requirements.
  3. Once done, copy the modified image tracking code and paste it inside the <head> tag on all the website pages you want to track (placed after the CMP initialisation script).

Modifying the Image tracker code

To ensure Matomo respects user consent, you may need to modify the image tracker based on how your consent manager handles consent categories and events.

Each CMP, such as CookieScript, CookieYes, and Cookiebot has its own approach for signalling when consent has been granted and which categories have been accepted. We provide integration guides for several popular consent manager platforms. These guides include consent handling scripts that you can reference to correctly modify the image tracker for your setup.

Take note of the consent event name your CMP triggers when the user responds (e.g. cookieyes_consent_update) and the category name that applies to Matomo tracking (e.g. "analytics", "statistics", or "performance"). You can use this information to modify the image tracker so it is only triggered after valid consent has been received.

The default image tracker sends the tracking request immediately when the page loads, without waiting for consent.

<!-- Matomo Image Tracker-->
<img referrerpolicy="no-referrer-when-downgrade" src="https://mysubdomain.matomo.cloud/matomo.php?idsite=1&amp;rec=1" style="border:0" alt="" />
<!-- End Matomo -->

Since it’s a plain HTML <img> tag, most Consent Management Platforms (CMPs) won’t automatically block it.

To enforce consent, you can modify the image tracker to follow the CMP’s requirements. This example updates the image tracker to integrate with the CookieScript CMP:

  • data-src: Replaces src to prevent the image from loading automatically.
  • data-cookiescript="accepted": Uses a defined CookieScript event to inform the CMP that this element should only be activated after user consent.
  • data-cookiecategory="performance": Links the tracking request to the CookieScript default Performance category for analytics. 
<img 
  data-src="https://mysubdomain.matomo.cloud/matomo.php?idsite=1&rec=1" 
  data-cookiescript="accepted" 
  data-cookiecategory="performance" 
  referrerpolicy="no-referrer-when-downgrade" 
  style="border:0" 
  alt="" />

Validate the Integration

After installing the modified image tracker, you can test the tracking behaviour for different regions to validate your privacy compliance setup.

  • To simulate different locations, use a VPN during testing.
  • Open your website and use the CMP widget to decline tracking consent.
  • In your Matomo instance, select the Visits in Real-time report, and check that no tracking requests are sent.
  • Next, grant consent and verify that tracking starts in your Matomo instance.
  • Revoke consent and perform some test actions – then check your activity was not recorded in the Visits in Real-time report.

This simple test confirms that the integration correctly respects regional privacy requirements and only activates tracking after consent is granted.

Method 2: Opt-out Tracking (CNIL Exemption)

The French supervisory authority, the Commission nationale de l’informatique et des libertés (CNIL) allows specific configuration of Matomo Analytics to be used without prior consent, provided that strict conditions are met. This is commonly referred to as CNIL consent exemption for audience measurement tools.

Organisations relying on the CNIL consent exemption can track website visitors by default provided that all exemption conditions are met:

  • The data is collected only for audience measurement their visitors are informed about and can object to tracking via an opt-out mechanism;
  • The cookies or other tracking tools used solely for audience analytics;
  • The tracking meets required time limits and produces specific aggregated data sets; and
  • The trackers are not used for identification, profiling, or cross-site tracking of visitors.

Note: To comply with this exemption, you must implement the necessary settings in Matomo to ensure data collection remains privacy-friendly and adheres to CNIL’s guidelines.

Refer to the CNIL consent exemption for Matomo Analytics Configuration Guide (English version) or (French version).

While CNIL’s exemption is specific to France, supervisory authorities in a small number of other EU countries have also exempted narrow scope of website analytics from consent (with opt-out right). The Opt-out tracking method can also be used in the context of those exemptions, if Matomo is configured in line with the specific requirements. Refer to the ePrivacy Directive overview, National Implementations, and Matomo’s Website Analytics Guide for details.

To configure tracking under the CNIL exemption (opt-out model), it’s important to assess whether your site qualifies for this setup. Consult with your data privacy officer or legal team before relying on the CNIL exemption.

If you fully comply with CNIL’s criteria for exempt audience measurement tools, there are different approaches you can take to integrate with your consent manager platform (CMP).

  1. Your website targets visitors in countries where CNIL or very similar exemption exists (e.g., France, Spain, Italy), or you have an establishment in such countries:
    • You can configure your CMP to either load the Matomo Image tracker and start tracking without prior consent, or
    • Re-categorise the Matomo Image tracker script as Essential/Necessary.
    • The CMP banner must clearly inform users about the use of consent exempt website analytics tracking and include a visible and easily accessible opt-out mechanism (e.g. a link to your privacy policy with an opt-out checkbox).
  2. If your website serves a broader audience that targets visitors from countries that require prior consent for cookie based or cookieless website analytics (e.g. most of EU countries):
    • Consider splitting your banner configuration if the CMP supports region-specific geotargeting and consent rules.
  3. Follow the steps in this guide, How to include a web analytics opt-out feature on your site to add the embedded Matomo opt-out form to your website. The form includes all required JavaScript to allow users to opt-out of tracking.
  4. Alternatively, you can create a custom opt-out form using HTML and JavaScript, as explained in this developer guide.

⚠️ If you use Matomo features like Heatmaps, User ID, Ecommerce, Advertising Conversion, or Session Recording, or you want to access or export raw data you must switch to Method 1 (Consent-based Tracking), as these features fall outside the exemption.

Validate the Integration

After installing the image tracker, you can test the tracking behaviour for different regions to validate your privacy compliance setup.

  • Perform test actions on your website and view the Visits in Real-time report to verify tracking requests are sent to Matomo.
  • Select to opt-out of tracking.
  • Perform test actions on your website and view Visits in Real-time report to ensure no tracking requests are sent to Matomo after opting out.
  • Change the settings to opt back in and resume tracking.
  • Perform test actions on your website and view the Visits in Real-time report to ensure tracking requests are sent to Matomo.

This test confirms that the integration respects the user’s choice to opt out and behaves in accordance with CNIL’s exemption criteria.

Disclaimer: The use of any third-party tools (plugins, extensions, platforms, APIs, widgets, etc.) is at your own risk. Matomo does not own, control, maintain or support any third-party tools that integrate with our product. We recommend checking your privacy setup is correctly configured across your environment when using any third-party tools.

Previous FAQ: When tracking visitors using an image beacon instead of the JavaScript tracker, what are the differences?