Integrate iubenda Privacy Controls and Cookie Solution CMP with Matomo Tag Manager

Cloud Auto-hébergement

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) helps website owners manage visitor consent for cookie-based and cookieless tracking. It typically presents visitors with a consent banner explaining data processing activities and allows them to accept or decline specific purposes, such as Analytics or Marketing.

You can integrate a consent manager with Matomo using the Matomo tracking code or Matomo Tag Manager.

Matomo supports three tracking approaches, depending on your organisation’s legal requirements and tracking needs:

  1. 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 met and users are offered a clear opt-out mechanism. Refer to the guide Configure CNIL exemption opt-out tracking with a consent manager (CMP).
  2. 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.
  3. 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).

This guide explains how to configure Consent-based tracking or Adaptive tracking using Matomo Tag Manager. If you are using the JavaScript tracking code, follow the iubenda and Matomo integration guide.

Before you start

  1. Ensure the Matomo Tag Manager container code is installed on all web pages you want to track. If you have not created a container or configured tracking, follow the setup guide first.
  2. Complete the necessary steps to configure your iubenda cookie banner in line with the consent method used and the legal requirements that apply to your website.
  3. iubenda may identify Matomo during its website scan and will classify it as an Analytics service.
  4. You will need to manually add the service to your CMP configuration.
  5. The example below shows adding the Matomo Cloud service. If you use Matomo On-Premise, select Matomo (self-hosted).
    add service in iubenda

Configure iubenda callbacks

After configuring your iubenda cookie banner, add the callbacks directly in the iubenda dashboard before embedding the consent manager on your website. The callbacks notify Matomo when the consent manager is ready or a visitor expresses their consent preferences.

  1. Click Edit and then open Advanced settings.
    edit iubenda configuration
  2. Scroll down to Callbacks to add the relevant functions.
  3. Add to onReady:
    function() {
    setIubMatomoConnect();
    }
  4. Add to onPreferenceFirstExpressed:
    function() {
    setIubMatomoConnect();
    }
  5. Save the configuration.
    add callbacks in iubenda
  6. Return to the Core compliance dashboard.
  7. Click Embed and copy the iubenda initialisation script shown on your screen.
    edit iubenda config
  8. Follow the next section below to add the copied code to a custom HTML tag in Matomo Tag Manager.
  1. After copying the iubenda code, open your container in Tag Manager.
  2. Go to Tags and click Create a New Tag.
  3. Select the Custom HTML tag and paste the iubenda code into the Custom HTML field.
  4. Link a Pageview trigger, depending on your setup. Always test your configuration to ensure there are no timing issues.
  5. Set the Position to Head start.
  6. Use Preview/Debug mode to confirm the cookie banner loads.
  7. Check the browser console to ensure no errors occur.
  8. Ensure the iubenda Custom HTML tag runs before the Matomo Analytics tags.

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.

This next script must be added to your existing iubenda custom HTML tag that contains the embedded consent manager code. It checks whether the visitor has accepted Statistics consent (Purpose 4) in iubenda and communicates the consent status to Matomo.

If consent is granted, Matomo tracking is enabled. When consent is revoked or denied, Matomo disables tracking and removes cookies (if used).

  1. In your Tag Manager container, go to Tags and open the iubenda custom HTML tag created earlier.
  2. Copy the following script and paste it below the consent manager code in the custom HTML tag.
<script>
window._paq = window._paq || [];

window.setIubMatomoConnect = function () {
  if (!window._iub?.cs?.api?.getPreferences) {
    return;
  }

  var preferences = window._iub.cs.api.getPreferences();
  var consentGiven = preferences?.purposes?.[4] === true;

  if (consentGiven) {
    window._paq.push(['setConsentGiven']);
  } else {
    window._paq.push(['forgetConsentGiven']);
  }
};
</script>

Your iubenda custom tag should now include two scripts.
iubenda scripts added to custom html tag

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.

  1. In your Tag Manager container, go to Variables and edit the Matomo Configuration Variable.
  2. Scroll down to the consent options and enable Require tracking consent.
  3. Click Update to save the changes.

After completing the configuration, test the setup to confirm that Matomo responds correctly when visitors grant or deny consent to track.

  1. Use Preview/Debug mode to verify that Matomo applies the visitor’s consent preferences before tracking begins.
  2. Ensure the iubenda Custom HTML tag executes before the Matomo Analytics tags.
  3. Open your website and use the CMP widget to decline consent.
  4. Perform some test actions and check your activity was not recorded in the Matomo report Visitors > Real-time.
  5. Use the browser’s developer tools and view the Network tab to check no tracking requests (matomo.php) were sent.
  6. Grant consent, perform test actions and view the Real-time report and Network tab to confirm tracking requests were sent.
  7. Revoke consent and check that Matomo stops tracking.

Method 2: 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.

This next script must be added to your existing iubenda custom HTML tag that contains the embedded consent manager code. It checks whether the visitor has accepted Statistics consent (Purpose 4) in iubenda and communicates the consent status to Matomo.

If the visitor grants consent, Matomo can use tracking cookies. If consent is denied or withdrawn, Matomo continues tracking without cookies and removes existing Matomo tracking cookies.

  1. In your Tag Manager container, go to Tags and open the iubenda custom HTML tag created earlier.
  2. Copy the following script and paste it below the consent manager code in the custom HTML tag.
<script>
window._paq = window._paq || [];

window.setIubMatomoConnect = function () {
  if (!window._iub?.cs?.api?.getPreferences) {
    return;
  }

  var preferences = window._iub.cs.api.getPreferences();
  var consentGiven = preferences?.purposes?.[4] === true;

  if (consentGiven) {
    window._paq.push(['setCookieConsentGiven']);
  } else {
    window._paq.push(['forgetCookieConsentGiven']);
  }
};
</script>

Your iubenda custom tag should now include two scripts.

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.

  1. In your Tag Manager container, go to Variables and edit the Matomo Configuration Variable.
  2. Scroll down to the consent options and enable Require cookie consent.
  3. Click Update to save the changes.

After completing the configuration, test the setup to confirm that Matomo responds correctly when visitors grant or deny consent to track.

  1. Use Preview/Debug mode to verify that Matomo applies the visitor’s consent preferences before tracking begins.
  2. Ensure the iubenda Custom HTML tag executes before the Matomo Analytics tags.
  3. Open your website and use the CMP widget to decline consent.
  4. Perform some test actions and check your activity is recorded in the Visitors > Real-time report report.
  5. Use the browser’s developer tools and view the Network tab to check that tracking requests (matomo.php) were sent.
  6. Open the Application/Storage tab to confirm no Matomo cookies are present.
  7. If you grant consent, check that Matomo sets the cookies.
  8. Revoke consent and confirm Matomo removes the cookies.

Rejecting Statistics consent prevents Matomo from using tracking cookies but does not stop cookieless tracking. If visitors must be able to opt out of all tracking, configure an opt-out mechanism.

Troubleshooting

If Matomo does not respond to consent preferences, review the following:

  • Check the browser Console for JavaScript errors.
  • Confirm the callback functions use the correct syntax and the setIubMatomoConnect() function is defined.
  • Check that Matomo is assigned to the Statistics consent purpose in your iubenda configuration.
  • If using cookieless tracking, review iubenda’s automatic blocking settings.

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: Integrate iubenda Privacy Controls and Cookie Solution CMP with Matomo