Configure consent for marketing tags in Matomo Tag Manager

Cloud On-Premise

Depending on your privacy requirements, marketing tags configured in Matomo Tag Manager, such as the Facebook Pixel, Google Ads, or LinkedIn Insight tags, may require visitor consent before they can load or send data.

When integrating with a consent manager platform (CMP), you can configure your Tag Manager container to check the visitor’s consent status. The CMP confirms if the required consent has been granted, and when consent is granted, the marketing tag will fire.

This guide explains how to configure consent for marketing tags using Usercentrics CMP and the Facebook Pixel tag as an example. The same approach can be adapted for other marketing tags and CMPs.

Before you start

Ensure the following prerequisites are set up:

  1. A consent management platform (CMP) is configured and installed on your website.
  2. The relevant marketing service is set up in the CMP configuration. For example, in Usercentrics, the Facebook Pixel is added as a Data Processing Service (DPS).
  3. Your Matomo Tag Manager container is installed on your web pages before the closing </head> tag.

With consent-based tracking, Matomo must first be configured to wait for explicit consent before it starts tracking. If consent is denied or revoked, tracking stops.

Follow the Matomo and Usercentrics integration guide (or relevant consent manager guide) to configure tracking consent for Matomo. The setup includes:

  1. Enable Require tracking consent in the Matomo Configuration Variable, and
    enable require consent
  2. Add a Custom HTML tag to respond to consent changes from Usercentrics.

Once Matomo tracking consent is configured, you can then set up consent for marketing tags in the same container.

Marketing tags should only fire when the visitor has granted consent. In Matomo Tag Manager, you can pass the consent status from your CMP to the _mtm data layer. A trigger can then use this value to determine if the marketing tag can fire.

In this step, you will need to create a Custom HTML tag that passes the relevant Usercentrics consent status to the _mtm data layer.

  1. Open your Tag Manager container and go to Tags.
  2. Click Create New Tag and choose the Custom HTML tag type.
  3. Provide a user-friendly Name and optional Description.
  4. Assign a Pageview trigger.
  5. For a Usercentrics service named Facebook Pixel, add the following JavaScript in the Custom HTML field and save the tag.

Note: The script waits for Usercentrics to become available and retrieves the visitor’s current consent settings. It checks whether consent was granted for the Facebook Pixel service and then pushes a usercentricsConsentUpdated event to the _mtm data layer with metaConsent set to true when consent is granted or false when it is not.

<script>
(function () {
  var waitForUsercentricsCount = 0;

  function pushMetaConsent(consentData) {
    if (!consentData || !consentData.services) {
      return;
    }

    var services = Object.values(consentData.services);

    var metaService = services.find(function (service) {
  return service.name === "Facebook Pixel";
});

    var metaConsent = !!(
      metaService &&
      metaService.consent &&
      metaService.consent.given
    );

    window._mtm = window._mtm || [];
    window._mtm.push({
      event: "usercentricsConsentUpdated",
      metaConsent: metaConsent
    });
  }

  function initialiseUsercentricsConsent() {
    if (
      !window.__ucCmp ||
      typeof window.__ucCmp.getConsentDetails !== "function"
    ) {
      if (waitForUsercentricsCount < 40) {
        waitForUsercentricsCount++;
        setTimeout(initialiseUsercentricsConsent, 250);
      }
      return;
    }

    // Retrieve the current consent state.
    window.__ucCmp.getConsentDetails()
      .then(pushMetaConsent)
      .catch(function () {
        // Consent status could not be retrieved.
      });

    // Listen for subsequent consent changes.
    window.addEventListener("UC_CONSENT", function (event) {
      pushMetaConsent(event.detail);
    });
  }

  initialiseUsercentricsConsent();
})();
</script>

Next, add a Data Layer variable that retrieves the metaConsent value.

  1. Go to Variables and click Create New Variable.
  2. Choose the Data Layer variable type.
  3. Enter a descriptive Name, for example Usercentrics – Meta Consent.
  4. In the Data Layer Variable Name field, enter metaConsent.
    add data layer variable
  5. Save the variable and use it as a condition when configuring the trigger for the Facebook Pixel tag.

Create a Custom Event trigger

The trigger will listen for the usercentricsConsentUpdated event pushed to the data layer and uses the condition to fire only when Facebook Pixel consent is granted.

  1. Go to Triggers and click Create New Trigger.
  2. Select the Custom Event trigger type.
  3. Enter a descriptive Name, for example Usercentrics – Meta Consent Granted.
  4. In the Event Name field, enter: usercentricsConsentUpdated
  5. Add a condition using the Usercentrics – Meta Consent Data Layer variable and set it to equals true.
  6. Save the trigger and it will fire when Usercentrics reports a consent update and metaConsent is true.
    add custom event trigger for consent

Add or modify the marketing tag

  1. Edit existing or configure new marketing tags, for example Facebook Pixel, Google Ads, or LinkedIn Insights.
  2. Ensure the Custom Event trigger is assigned to the marketing tag instead of a standard Pageview trigger. This prevents the tag from firing simply because the page has loaded.

After configuring consent-based tracking for Matomo and a marketing tag, the container will include four tags:

  1. Two Custom HTML tags: One tag is created when integrating the CMP with Matomo and it manages tracking based on the visitor’s consent status. The second tag pushes the marketing service consent status to the data layer.
  2. Matomo Analytics tag: Handles Matomo tracking according to the consent configuration.
  3. Marketing tag: For example, a Facebook Pixel tag that fires when the corresponding consent trigger confirms consent has been granted.

To verify consent-based tracking is working correctly, test the configuration before publishing the Matomo Tag Manager container.

  1. Open Preview / Debug mode in Tag Manager and the browser developer tools.
  2. On your website, decline marketing consent through the CMP widget and reload the page.
  3. Confirm that the marketing tag does not fire.
  4. In the developer tools > Network tab, check that no requests were sent to the third-party platform.
  5. Next, grant marketing consent and confirm that the tag fires as expected.
  6. You can test revoking marketing consent and then confirm no subsequent marketing tags or events fire without the required consent.
  7. Check the Visitors > Real-time or Visits Log to confirm if a visit should appear.

Troubleshooting

If a marketing tag does not fire after consent is given, open your browser developer tools and check the Console for JavaScript errors relating to the Custom HTML tag or CMP.

Check the service name used in the Custom HTML script exactly matches the service configured in your CMP. For example, if Usercentrics lists the data processing service as Facebook Pixel, use Facebook Pixel in the script. Matching the name ensures the script checks consent for the correct service.

Take note of the service name, consent status or event being checked, and any CMP-specific functions or variables. A missing value, incorrect service name, or syntax error can prevent the marketing tag from firing.