OneTrust integration

If you choose to use OneTrust as your consent manager, you can set up Piwik PRO to collect data based on the visitor’s consent. Keep in mind that OneTrust and Piwik PRO use different consent types, so you’ll have to map them yourself. Also, you’ll need to add a JavaScript code to each page of your site. 

In this article, we’ll show you how to map consent types and integrate with OneTrust.

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 OneTrust 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.

   

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.

   

9. Click Save.
10. Done! Now Piwik PRO is ready for the integration with OneTrust.

Map consent types between OneTrust and Piwik PRO

In the next step, you’ll need to map at least one consent type from OneTrust to one or more consent types in Piwik PRO. But before you do this, it’s important to understand the differences in consent types between the two products.

Consent types in Piwik PRO

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.

Consent types in OneTrust

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

Mapped consent types

Here’s an example of how to map consents.

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

Add a tag with the JS code

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.

   <script>
       (function(consentMap, options) {...})
       (consentMap, options)
   </script>

   Parameters

   consentMap (object, required)
   An object that accepts consent IDs from OneTrust 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.

   Example:

   <script>
       (function(e,t){var n,i,c={},s=0,o=0,a="Piwik PRO OneTrust integration: ",r=!t||isNaN(t.logLevel)?0:t.logLevel,l=!t&&isNaN(t.initializationRetryDelay)?-1:t.initializationRetryDelay;function u(e){r>=0&&console.error(a+e)}function f(e,t){if(r>=1){if(t){if(console.table){console.info(a+e),console.table(t);return}e+=": "+JSON.stringify(t)}console.info(a+e)}}function p(t){var n,i,a={consents:{}},l=[],t=t||window.OnetrustActiveGroups.split(",");if(r>=1){for(n=0;n<t.length;n+=1)(i=t[n])&&l.push({"OneTrust Id":i,"Piwik PRO Id":(e[i]||[]).join(",")});f('Selected OneTrust groups (Piwik PRO Id is "" when no mapping found)',l)}var p,d,k,g,m=["analytics","ab_testing_and_personalization","conversion_tracking","marketing_automation","remarketing","user_feedback","custom_consent"],C={};for(d in e)if(e.hasOwnProperty(d))for(p=0,g=t.indexOf(d)>-1?1:0,c[d]=g;p<e[d].length;p+=1)k=e[d][p],m.indexOf(k)>=0&&(C[k]=d,a.consents[k]={status:g});s=0,ppms.cm.api("getComplianceSettings",function(e){if(void 0===e.consents||o)s=1;else{var t,n,i,a;for(t=0;t<m.length;t+=1)a=c[i=C[n=m[t]]]?1:0,C.hasOwnProperty(n)&&(void 0===e.consents[n]||e.consents[n].status!==a)&&(s=1)}},function(){u("getComplianceSettings request failed")}),1===s&&ppms.cm.api("setComplianceSettings",a,function(){f("setComplianceSettings request successfull")},function(){u("setComplianceSettings request failed")})}function d(e){e.length>0?(o=!0,ppms.cm.api("setInitialComplianceSettings",{consents:e},function(){f("setInitialComplianceSettings request successfull")},function(){u("setInitialComplianceSettings request failed")})):o=!1}function k(){ppms.cm.api("trackRejectAllClick",function(){f("trackRejectAllClick request successfull")},function(){u("trackRejectAllClick request failed")})}function g(){ppms.cm.api("trackReminderWidgetView",function(){f("trackReminderWidgetView request successfull")},function(){u("trackReminderWidgetView request failed")})}function m(e,t){return(e||"").indexOf(t)>-1}function C(e){p(e.detail)}function h(){ppms.cm.api("getNewComplianceTypes",d,function(){u("getNewComplianceTypes request failed")}),OneTrust.IsAlertBoxClosed()||ppms.cm.api("trackMainFormView",function(){f("trackMainFormView request successfull")},function(){u("trackMainFormView request failed")}),window.addEventListener("click",function(e){var t,n=function e(t,n){return t?t.closest?t.closest(n):(t.tagName||"").toLowerCase()===n.toLowerCase()?t:e(t.parentNode,n):null}(e.target,"button");if(n){switch(n.id){case"onetrust-accept-btn-handler":ppms.cm.api("trackAgreeToAllClick",function(){f("trackAgreeToAllClick request successful")},function(){u("trackAgreeToAllClick request faied")});return;case"onetrust-reject-all-handler":k();return;case"onetrust-pc-btn-handler":case"onetrust-cookie-btn":g();return}m(t=n.className,"ot-floating-button__open")?g():m(t,"ot-floating-button__close")||m(t,"onetrust-close-btn-handler")?ppms.cm.api("trackCloseButtonClick",function(){f("trackCloseButtonClick request successfull")},function(){u("trackCloseButtonClick request failed")}):m(t,"ot-pc-refuse-all-handler")?k():m(t,"save-preference-btn-handler")&&ppms.cm.api("trackSaveChoicesClick",function(){f("trackSaveChoicesClick request successfull")},function(){f("trackSaveChoicesClick request failed")})}},!0),p(),OneTrust.OnConsentChanged(C)}function O(){window.OneTrust?h():(i=window.OptanonWrapper,window.OptanonWrapper=function(){"function"==typeof i&&i.apply(this,arguments),h()})}l<0?O():n=setInterval(function(){(window.OptanonWrapper||window.OneTrust)&&(O(),clearInterval(n))},l)})
   (
      {
          'C0002': ['analytics'],
          'C0003': ['ab_testing_and_personalization'],
          'C0004': ['marketing_automation', 'remarketing', 'conversion_tracking']
      },
      {
          logLevel: 1 // logLevel=1 will display errors in the browser console
      }
   );
   </script>

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: OneTrust 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 OneTrust consent form. If we look at our example, the integration will work like this:

    A visitor consents on your OneTrust consent form	Piwik PRO fires tags with this consent type
    Performance Cookies	Analytics
    Functional Cookies	A/B testing or personalized content
    Targeting Cookies	User feedback, Remarketing, Conversion tracking