Integrate CookieYes CMP with Matomo Tag Manager FAQ - Tag Manager

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 cookie-based or cookieless 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.

CMP integration with Matomo can be implemented using the Matomo JavaScript tracking code or Matomo Tag Manager. The tracking code method is covered in a separate guide.

This guide focuses on three integration methods using Matomo Tag Manager.

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

Consent-based Tracking: For websites targeting users in countries that require prior consent for use of cookies and similar technologies for analytics and marketing (for example, most or EU and EEA countries), enable cookieless or cookie-based Matomo tracking only after obtaining visitor consent.
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.
Adaptive Tracking: For websites operating outside the EU/UK/EEA, in countries where prior consent is either not required or only required when the analytics processes personal data, you can enable cookie-based tracking with consent and fallback to cookieless tracking if consent is not given (unless the visitor opts out of all tracking).

Before you start

Create your CookieYes account.
Complete the necessary steps to configure your cookie banner in line with the consent method used and the legal requirements that apply to your website.
Add your Matomo Tag Manager code to your website pages that you want to track.
- Open the Tag Manager container > Install code.
- Copy and paste the code snippet in your website’s code within the <head> tag on every webpage you want to track.
You can choose to install the consent manager initialisation script in one of two ways:
- Follow the CookieYes instructions to add the script to your website’s code within the <head> tag on every webpage you want to track; OR
- Use Matomo Tag Manager’s built-in CookieYes tag.

Note: Only use one implementation method: either the CookieYes script in your website code OR the CookieYes tag in Matomo Tag Manager, not both. This will ensure a consistent consent process. Running two consent implementations in parallel may result in inconsistent or incorrect consent handling, (e.g. relying on opt-out where opt-in is required) and non-compliance.

Configure the CookieYes Tag

If you’re already using CookieYes and added its script directly to your website’s code, you will need to remove it when switching to the CookieYes tag in Matomo Tag Manager. The following steps explain how to configure the CookieYes tag.

In Tag Manager, navigate to Tags and click Create New Tag.
Choose the CookieYes tag.
Enter your CookieYes Website key found in the source attribute of your CookieYes installation code (e.g. src= "https://cdn-cookieyes.com/client_data/your_website_key/script.js") – located in your CookieYes account > Dashboard > Get installation code.
In the section, Configure when the tag should do this, select a Pageview trigger.
Click Create New Tag to save the CookieYes tag.

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

This method can operate in either cookieless (JavaScript-based) or cookie-based mode, but tracking is only activated after the visitor gives consent. When consent is revoked or denied, any existing Matomo cookies are removed from the visitor’s browser and tracking stops.

To implement consent-based tracking using Matomo Tag Manager, complete the following configuration steps to ensure tracking starts after the visitor gives consent.

Note: The Tag Manager container must include a Matomo Analytics pageview tracking tag linked to the Matomo Configuration variable and Pageview trigger.

Update the Matomo Configuration Variable

To ensure Matomo respects consent preferences, you need to update the Matomo Configuration Variable used across your Matomo Analytics tags. This variable controls how tracking is applied, specifically to wait for explicit consent before tracking.

In Tag Manager, navigate to Variables and open the Matomo Configuration Variable.
Scroll down to the consent options and enable Require tracking consent.
Click Update to save the changes.

Add a DOM Ready Trigger

We recommend using the DOM Ready trigger by default when implementing your consent handling script. However, if you notice that it fires before your consent manager or tracking scripts are fully available, consider using the Window Loaded trigger.

Always test your setup to ensure there are no timing issues and tracking does not begin before consent is granted.

Navigate to Triggers and click Create New Trigger.
Choose the DOM Ready trigger.
Click Create New Trigger to save.

Create a Custom HTML Tag

Next, you will need to create a Custom HTML tag to insert the Matomo consent handling script that listens for consent updates and enables/disables tracking when consent granted/denied.

Navigate to Tags and click Create New Tag.
Choose the Custom HTML tag and provide a custom name (optional).
Copy and paste the script below into the Custom HTML field.

<script>
var waitForTrackerCount = 0;
function matomoWaitForTracker() {
  if (typeof _paq === 'undefined') {
    if (waitForTrackerCount < 40) {
      setTimeout(matomoWaitForTracker, 250);
      waitForTrackerCount++;
      return;
    }
  } else {
    document.addEventListener("cookieyes_consent_update", function (eventData) {
        const data = eventData.detail;
        consentSet(data);
    });   
  }
}
function consentSet(data) {
   if (data.accepted.includes("analytics")) {           
       _paq.push(['setConsentGiven']);
       _paq.push(['rememberConsentGiven']);
   } else {
       _paq.push(['forgetConsentGiven']);                      
   }
}
matomoWaitForTracker();
</script>

Link the DOM Ready trigger.
Set the Position to Head Start to define where the code gets inserted into the website’s code.
Click Create New Trigger to save.

Validate the Integration

Once you have configured Matomo Tag Manager, you can test the tracking behaviour to validate your privacy compliance setup.

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.
If using cookie-based tracking, open the browser’s developer tools and view the Application or Storage > Cookies tab to confirm cookies were set.
Revoke consent and confirm the Matomo tracking cookies are deleted from the browser.
Perform some test actions and 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. Learn more about Testing Tips for integrating consent managers with Matomo Tag Manager.

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 those specific requirements. Refer to the ePrivacy Directive overview, National Implementations, and Matomo’s Website Analytics Guide for details.

If you are using Matomo Tag Manager and want 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).

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:
- Configure your CMP to either load Matomo Analytics cookies and start tracking without prior consent, or
- Re-categorise the Matomo cookies 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).
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.
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.
Alternatively, you can create a custom opt-out form using HTML and JavaScript, as explained in this developer guide.

Configure Matomo Tag Manager

When using Matomo Tag Manager in an opt-out configuration:

Do not use consent-based triggers for Matomo Analytics tags. The tags should fire automatically, even without consent.
Ensure all active tags fall within CNIL-compliant functionality (e.g. does not use UserID tracking).
Check the Matomo Configuration Variable does not have consent settings enabled (e.g., Require tracking or cookie consent).

Validate the Integration

Once you have configured Matomo Tag Manager, 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.
Open the browser’s developer tools and view the Application or Storage > Cookies tab to verify that the mtm_consent_removed cookie is set.
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.

⚠️ 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.

Method 3: Adaptive Tracking

The Adaptive Tracking method can be used in regions where prior consent for analytics cookies or other trackers:

are not legally required (but you want to minimise the data you collect),
are not required for pseudonymised non-sensitive personal data or
are only required if certain personal data is processed.

You can minimise the data you collect by configuring the Matomo privacy settings.

This method allows tracking to begin immediately in cookieless mode, with the option to request consent for cookie-based tracking. When the website visitor provides consent, tracking switches to cookie-based mode. If consent is denied or later revoked, tracking continues in cookieless mode.

To implement consent for cookie-based tracking using Matomo Tag Manager, complete the following configuration steps to ensure cookies are placed only after the visitor gives consent.

Note: The Tag Manager container must include a Matomo Analytics pageview tracking tag linked to the Matomo Configuration variable and Pageview trigger.

Update the Matomo Configuration Variable

In Tag Manager, navigate to Variables and open the Matomo Configuration Variable.
Scroll down to the consent options and enable Require cookie consent.
Click Update to save changes.

Add a DOM Ready Trigger

We recommend using the DOM Ready trigger by default when implementing your consent handling script. However, if you notice that it fires before your consent manager or tracking scripts are fully available, consider using the Window Loaded trigger.

Always test your setup to ensure there are no timing issues and cookies are not set before consent is granted.

Navigate to Triggers and click Create New Trigger.
Choose the DOM Ready trigger.
Click Create New Trigger to save.

Create a Custom HTML Tag

Next, you will need to create a Custom HTML tag to insert the script listens for consent updates and enables/removes cookies when cookie consent is granted/denied.

Navigate to Tags and click Create New Tag.
Choose the Custom HTML tag and provide a custom name (optional).
Copy and paste the script below into the Custom HTML field.

<script>
    var waitForTrackerCount = 0;
    function matomoWaitForTracker() {
        if (typeof _paq === 'undefined') {
            if (waitForTrackerCount < 40) {
                setTimeout(matomoWaitForTracker, 250);
                waitForTrackerCount++;
                return;
            }
        } else {
            document.addEventListener("cookieyes_consent_update", function (eventData) {
                const data = eventData.detail;
                consentSet(data);
            });
        }
    }
    function consentSet(data) {
        if (data.accepted.includes("analytics")) {
            _paq.push(['rememberCookieConsentGiven']);
            _paq.push(['setConsentGiven']);
        } else {
            _paq.push(['forgetCookieConsentGiven']);  
            _paq.push(['deleteCookies']);
        }
    }
    matomoWaitForTracker();
    </script>

Link the DOM Ready trigger.
Set the Position to Head Start to define where the code gets inserted into the website’s code.
Click Create New Trigger to save.

Validate the Integration

Once you have configured Matomo Tag Manager, 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 cookie consent.
Use the browser’s developer tools and view the Application or Storage > Cookies tab to confirm cookies were not set.
In the Visits in Real-time report, check that tracking requests are still sent.
Next, grant / revoke consent and confirm cookies were set / removed as expected.

This simple test confirms that the integration correctly respects regional privacy requirements and only uses cookies after consent is granted. Learn more about Testing Tips for integrating consent managers with Matomo Tag Manager.

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.

Next FAQ: Using Osano Consent Manager CMP with Matomo Tag Manager

Previous FAQ: Using OneTrust Consent Manager CMP with Matomo Tag Manager

Before you start

Configure the CookieYes Tag

Method 1: Consent-based Tracking

Update the Matomo Configuration Variable

Add a DOM Ready Trigger

Create a Custom HTML Tag

Validate the Integration

Method 2: Opt-out Tracking (CNIL Exemption)

Configure the Consent Manager

Configure Matomo Tag Manager

Validate the Integration

Method 3: Adaptive Tracking

Update the Matomo Configuration Variable

Add a DOM Ready Trigger

Create a Custom HTML Tag

Validate the Integration

Feedback on this page