Didomi integration

Consent Manager

If you choose to use Didomi as your consent manager, you can set up Piwik PRO to collect data based on the visitor’s consent. The consent types used by Didomi differ from those used by Piwik PRO. We’ve created a mapping of the standard consent types from Didomi, but for any other types, you’ll need to map them yourself. Additionally, you’ll need to run a JavaScript code on each page of your site. 

In this article, we’ll give you instructions on how handle the mapping and integrate with Didomi.

Set up Piwik PRO

In the first step, you’ll need to set up Consent Manager in Piwik PRO so that it doesn’t display our consent form but still uses the consent management mechanism in Tag Manager. In the next steps, you’ll integrate Didomi into that mechanism.

To set up Consent Manager in Piwik PRO for your integration, follow these steps:

  1. Log in to Piwik PRO.
  2. Go to Menu > Administration.
  3. Navigate to Sites & apps.
  4. On the left, pick the site or app you want to set up.
  5. Navigate to Privacy.
  6. Turn on Ask visitors for consent.
    Ask visitor for consent in Piwik PRO
  7. Click View to customize the consent setting:
    • Collect anonymous data from non-consenting visitors: You can collect anonymous data from visitors who haven’t given their consent. Their IP addresses will be completely masked. You will not recognize new and returning visitors. And you will only know their country. It’s up to you to decide whether to use a session hash and visitor cookies for these visitors or not.
    • Use a session hash: If you use a session hash, it’ll be created for each session based on the visitor’s IP address, operating system, browser name, browser version, browser language, enabled browser plugins and site/app ID. This hash will help us recognize events that belong to the same session. Note: This setting applies to non-consenting visitors.
    • Use visitor cookies: If you use visitor cookies (_pk_id and _pk_ses), we’ll use them to recognize events that belong to the same session. They will expire 30 minutes after the last event. Note: This setting only applies to non-consenting visitors.

    Note: Some triggers in Tag Manager create cookies to function correctly. If you use one of the following conditions in triggers, we’ll set a cookie:

    • Event condition > Traffic source
    • Event condition > Returning visitor
    • Event condition > Campaign
    • Event condition > External referrer 
    • Multiplicity > Fire tag once per session
    • Multiplicity > Fire tag multiple times per session, excluding first
    • Multiplicity > Fire tag once per page view

    Make sure that tags with those triggers are set with the right consent type.
    We also set essential cookies that store a visitor’s consent decision. More about cookies

  8. Turn on Use a custom consent form.
    Didomi integration in Piwik PRO
  9. Click Save.
  10. Done! Now Piwik PRO is ready for the integration with Didomi.

Didomi offers a few standard consent types, also known as purposes. We already have predefined mappings for three of them: Select personalised ads, Measure ad performance and Develop and improve products. But if you want to make changes or add more mappings, you can use our manual mapping method. Just keep in mind that it’s important to understand the differences in consent types between the two products before making any adjustments.

In Piwik PRO, consent types are used to determine whether a specific tag (such as a tracking or marketing tag) should be fired for a visitor. If a tag requires the Analytics consent, it will only be activated for visitors who have given their consent for Analytics. This allows you to control which tags are activated for which visitors, based on their consent preferences.

Here’s a list of consent types in Piwik PRO.

Name API Description in UI
Analytics “analytics” We’ll collect information about your visit to our site. It helps us understand how the site is used –– what’s working, what might be broken and what we should improve.
A/B testing and personalization “ab_testing_and_personalization” We’ll use your data to customize our site to your needs. We’ll show you more relevant content and carry out A/B tests.
Conversion tracking “conversion_tracking” We’ll use your data to measure how effective our ads and on-site campaigns are.
Marketing automation “marketing_automation” We’ll use your data to send you more relevant email or text message campaigns. We’ll also use it to exclude you from campaigns that you might not like.
Remarketing “remarketing” We’ll use your data to show you more relevant ads on other sites and social media. We’ll use it to measure how effective our ads are. We’ll also use it to exclude you from campaigns that you might not like.
User feedback “user_feedback” We’ll use your data to learn how our user interface is working. It’ll help us to improve our site for all users.
Custom consent “custom_consent”

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Note: You can set an additional consent type here. In Tag Manager, it’ll be still called: Custom consent.

No consent is required

Note: It’s the type you can use for tags that don’t collect data. For example, tags that add a popup or content, or tags that change the look of your site.

Here’s a list of standard consent types in Didomi.

Name API name Description
Store and/or access information on a device “cookies” Cookies, device identifiers, or other information can be stored or accessed on your device for the purposes presented to you
Select basic ads "select_basic_ads" Ads can be shown to you based on the content you’re viewing, the app you’re using, your approximate location, or your device type
Create a personalised ads profile "create_ads_profile" A profile can be built about you and your interests to show you personalised ads that are relevant to you
Select personalised ads "select_personalized_ads" Personalised ads can be shown to you based on a profile about you ads that are relevant to you
Create a personalised content profile "create_content_profile" A profile can be built about you and your interests to show you personalised content that is relevant to you
Select personalised content "select_personalized_content" Personalised content can be shown to you based on a profile about you
Measure ad performance "measure_ad_performance" The performance and effectiveness of ads that you see or interact with can be measured
Measure content performance "measure_content_performance" The performance and effectiveness of content that you see or interact with can be measured. be measured
Apply market research to generate audience insights "market_research" Market research can be used to learn more about the audiences who visit sites/apps and view ads
Develop and improve products "improve_products" Your data can be used to improve existing systems and software, and to develop new products

Note: Didomi also offers custom consent types. If you use them, you’ll need to check their API names in Didomi > Data Manage > Purposes. The API name is a string that may include numbers. 

Read more in Didomi’s documentation.

Here’s the predefined mapping that we use for Didomi.

Didomi Piwik PRO
Name API name Name API name
Select personalised ads "select_personalized_ads" Remarketing "remarketing"
Measure ad performance "measure_ad_performance" Conversion tracking "conversion_tracking"
Develop and improve products "improve_products" User feedback "user_feedback"

Note: Our integration uses this mapping automatically. However, you can change this mapping using the manual method described below.

If you decide to manually map some consent types, you can use the example listed below.

Didomi Piwik PRO
"custom_name" "analytics"
"select_basic_ads" “custom_consent”
“select_personalized_content” “ab_testing_and_personalization”

Add a tag with the JS code

Now you need to prepare a JS code that will translate consents from Didomi to the ones in Piwik PRO and add it to your site using a tag.

To add a tag with the JS code, follow these steps:

  1. Here’s how the code you’ll use works. Take a moment to understand it, then adapt the example below to suit your needs.
        (function(consentMap, options) {...})
        (consentMap, options)


    consentMap (object, required)
    An object that accepts consent IDs from Didomi as keys and a list of consent IDs from Piwik PRO as values. For values, you need to use the API names for consent types, not the names from the UI. Example: 'analytics'.

    options (object, optional)
    An object containing the options used by the integration. List of options:

    • logLevel (integer, optional)
      The integration will display the required level of information and error messages in the browser console. Possible values: 0 (displays nothing), 1 (displays errors), 2 (displays errors and successful requests). Default value: 1.


        (function(e,i){var n={},t=0,s=0,c="Piwik PRO Didomi integration: ",o=!i||isNaN(i.logLevel)?1:i.logLevel;function r(e){o>0&&console.error(c+e)}function a(e){o>1&&console.info(c+e)}function l(){var i={consents:{}},c=Didomi.getUserStatus().purposes.global.enabled,o=Didomi.isConsentRequired(),l=["analytics","ab_testing_and_personalization","conversion_tracking","marketing_automation","remarketing","user_feedback","custom_consent"],u={};for(externalConsentName in e)if(e.hasOwnProperty(externalConsentName))for(ppasConsentTypeIterator=0,consentValue=!o||c.indexOf(externalConsentName)>-1?1:0,n[externalConsentName]=consentValue;ppasConsentTypeIterator<e[externalConsentName].length;ppasConsentTypeIterator+=1)ppasConsentName=e[externalConsentName][ppasConsentTypeIterator],l.indexOf(ppasConsentName)>=0&&(u[ppasConsentName]=externalConsentName,i.consents[ppasConsentName]={status:consentValue});t=0,ppms.cm.api("getComplianceSettings",function(e){if(void 0===e.consents||s)t=1;else{var i,c,o,r;for(i=0;i<l.length;i+=1)r=n[o=u[c=l[i]]]?1:0,u.hasOwnProperty(c)&&(void 0===e.consents[c]||e.consents[c].status!==r)&&(t=1)}a("getComplianceSettings request successfull")},function(){r("getComplianceSettings request failed")}),1===t&&ppms.cm.api("setComplianceSettings",i,function(){a("setComplianceSettings request successfull")},function(){r("setComplianceSettings request failed")})}function u(){ppms.cm.api("trackMainFormView",function(){a("trackMainFormView request successfull")},function(){r("trackMainFormView request failed")})}function d(){ppms.cm.api("trackCloseButtonClick",function(){a("trackCloseButtonClick request successfull")},function(){r("trackCloseButtonClick request failed")})}e.select_personalized_ads||(e.select_personalized_ads=["remarketing"]),e.measure_ad_performance||(e.measure_ad_performance=["conversion_tracking"]),e.improve_products||(e.improve_products=["user_feedback"]),ppms.cm.api("getNewComplianceTypes",function e(i){i.length>0?(s=!0,ppms.cm.api("setInitialComplianceSettings",{consents:i},function(){a("setInitialComplianceSettings request successfull")},function(){r("setInitialComplianceSettings request failed")})):s=!1},function(){r("getNewComplianceTypes request failed")}),window.didomiEventListeners=window.didomiEventListeners||[],window.didomiEventListeners.push({event:"consent.changed",listener:function(){l()}}),window.didomiEventListeners.push({event:"notice.clickagree",listener:function(){ppms.cm.api("trackAgreeToAllClick",function(){a("trackAgreeToAllClick request successful")},function(){r("trackAgreeToAllClick request faied")})}}),window.didomiEventListeners.push({event:"notice.clickdisagree",listener:function(){ppms.cm.api("trackRejectAllClick",function(){a("trackRejectAllClick request successfull")},function(){r("trackRejectAllClick request failed")})}}),window.didomiEventListeners.push({event:"notice.clickmoreinfo",listener:function(){ppms.cm.api("trackReminderWidgetView",function(){a("trackReminderWidgetView request successfull")},function(){r("trackReminderWidgetView request failed")})}}),window.didomiEventListeners.push({event:"notice.hidden",listener:function(){d()}}),window.didomiEventListeners.push({event:"notice.shown",listener:function(){u()}}),window.didomiEventListeners.push({event:"preferences.clickclose",listener:function(){d()}}),window.didomiEventListeners.push({event:"preferences.clicksavechoices",listener:function(){ppms.cm.api("trackSaveChoicesClick",function(){a("trackSaveChoicesClick request successfull")},function(){a("trackSaveChoicesClick request failed")})}}),window.didomiOnReady=window.didomiOnReady||[],window.didomiOnReady.push(function(e){e.notice.isVisible()&&u(),l()})})
        'custom_name': 'analytics',
        'select_basic_ads': ['custom_consent'],
        'select_personalized_content': ['ab_testing_and_personalization']
          }, {
        logLevel: 1 // logLevel=1 will display errors in the browser console
  2. Log in to Piwik PRO.
  3. Go to Menu > Tag Manager.
  4. Navigate to Tags.
  5. Click Add a tag.
  6. Name your tag. Example: Didomi integration.
  7. Pick the following tag type: Custom code (async).
  8. Click Next.
  9. In Tag code, paste the code from step 1.
  10. In Consent type, set the following type: No consent is required.
  11. Click Choose existing trigger.
  12. Pick the following trigger: All page views.
  13. Click Add a tag.
  14. Test your tag in debug mode.
  15. When you’re happy with how the tag works, click Publish.
  16. All done! Now tags in Piwik PRO will fire when the consent assigned to them is given on your Didomi consent form. If we look at our example, the integration will work like this:
    A visitor consents on your Didomi consent form Piwik PRO fires tags with this consent type
    Select personalised ads Remarketing
    Measure ad performance Conversion tracking
    Develop and improve products User feedback
    "custom_name" Analytics
    "select_basic_ads" Custom consent
    "select_personalized_content" A/B testing or personalized content

Was this article helpful?

Technical support

If you still have any questions, visit our community.
There’s always someone happy to help!

Back to help center