Getting started

Load the SDK

Script

We offer the Didomi SDK as a hosted JavaScript library that you can directly include on your website with a <script> tag.

Create a Consent Notice in the Didomi Console and get the script tag from the "3. Publish" section. Paste the tag the top of the <head> section of your HTML pages, before any other script tag.

Important: We recommend that you integrate the tags in the following order:

Conditioned vendors tags (header)
Didomi SDK (header)
Non conditioned vendors tags

Make sure to add the tag as close to the opening <head> tag on your page as possible, before any other tag gets embedded

Keep in mind that the role of our JavaScript SDK is to share consent information with all the other scripts on the page. In order to do so, it MUST be placed before any other tag or the tags from your vendors will not be able to collect consent information from us. Put it as close as possible to the opening <head> tag. If our SDK gets included after the other tags then the consent information will not be correctly shared and you will not be compliant with the GDPR requirements.

If you are using Content Security Policy for whitelisting content source domains, you have to make sure that you whitelist https://sdk.privacy-center.org/ and https://api.privacy-center.org/ to allow the Didomi SDK to operate normally.

Hybrid Apps: If you are embedding our tag as part of your hybrid app (Electron, Cordova, etc), make sure to set a custom domain as part of the configuration object.

React

You can skip this section if you don't have a React application.

We also provide a React component to simplify the integration of our SDK with React applications. To use it, please follow the steps below or go directly to our React component documentation: https://github.com/didomi/react

Install the library using npm.

npm install --save @didomi/react

2. Import the module in your app.

import { DidomiSDK } from '@didomi/react';

We recommend instantiating the component as soon as possible: the sooner you instantiate the component, the faster the banner will be displayed or the faster the consents will be shared with your partners and the ads displayed.

3. Instantiate the component in your app

<DidomiSDK
  iabVersion={2}
  gdprAppliesGlobally={true}
  onReady={didomi => console.log('Didomi SDK is loaded and ready', didomi)}
  onConsentChanged={cwtToken => console.log('A consent has been given/withdrawn', cwtToken)}
  onNoticeShown={() => console.log('Didomi Notice Shown')}
  onNoticeHidden={() => console.log('Didomi Notice Hidden')}
/>

The SDK will automatically pull the notice configuration from the Didomi Console.

For more information, please check our documentation : https://github.com/didomi/react

Testing from outside the EU

If your banner is configured to not display to non EU visitors, it might be tricky to configure and test if you are not located in the EU yourself. You can use the notice.ignoreCountry: true option if you are testing the banner from the US and force it to be shown to make sure it is working properly.

Another option is to add #didomi:notice.ignoreCountry=true to the URL in your browser bar to force the SDK to ignore the country on the page. Example: If your website is https://www.mywebsite.com, go to https://www.mywebsite.com/#didomi:notice.ignoreCountry=true and the notice should be displayed even if you are not in the EU.

Web based CTV application

Make sure that the notice that you will setup has been marked as CTV type (rather than Web) on the Console. See https://support.didomi.io/create-a-consent-notice-for-connected-tv-new-flow for more information.

Add the following code to your Web based CTV app. We recommend to embed it directly in the source of your HTML pages as adding it through a tag manager would slow down the loading of the notice.

<script type="text/javascript">(function(){function r(e){if(!window.frames[e]){if(document.body&&document.body.firstChild){var t=document.body;var n=document.createElement("iframe");n.style.display="none";n.name=e;n.title=e;t.insertBefore(n,t.firstChild)}else{setTimeout(function(){r(e)},5)}}}function e(n,a,o,c,d){function e(e,t,n,r){if(typeof n!=="function"){return}if(!window[a]){window[a]=[]}var i=false;if(d){i=d(e,r,n)}if(!i){window[a].push({command:e,version:t,callback:n,parameter:r})}}e.stub=true;e.stubVersion=2;function t(r){if(!window[n]||window[n].stub!==true){return}if(!r.data){return}var i=typeof r.data==="string";var e;try{e=i?JSON.parse(r.data):r.data}catch(t){return}if(e[o]){var a=e[o];window[n](a.command,a.version,function(e,t){var n={};n[c]={returnValue:e,success:t,callId:a.callId};if(r.source){r.source.postMessage(i?JSON.stringify(n):n,"*")}},a.parameter)}}if(typeof window[n]!=="function"){window[n]=e;if(window.addEventListener){window.addEventListener("message",t,false)}else{window.attachEvent("onmessage",t)}}}e("__tcfapi","__tcfapiBuffer","__tcfapiCall","__tcfapiReturn");r("__tcfapiLocator");(function(e,t){var n=document.createElement("link");n.rel="preconnect";n.as="script";var r=document.createElement("link");r.rel="dns-prefetch";r.as="script";var i=document.createElement("script");i.id="spcloader";i.type="text/javascript";i["async"]=true;i.charset="utf-8";var a="{{SDK-URL}}"+e+"/loader.js?platform=ctv&target_type=notice&target="+t;if(window.didomiConfig&&window.didomiConfig.user){var o=window.didomiConfig.user;var c=o.country;var d=o.region;if(c){a=a+"&country="+c;if(d){a=a+"&region="+d}}}n.href="{{SDK-URL}}";r.href="{{SDK-URL}}";i.src=a;var s=document.getElementsByTagName("script")[0];s.parentNode.insertBefore(n,s);s.parentNode.insertBefore(r,s);s.parentNode.insertBefore(i,s)})("{{Your-API-Key}}","{{Notice-ID}}")})();</script>

You will need to replace {{SDK-URL}} with our default SDK URL: https://sdk.privacy-center.org/ or use your own domain. You will also have to replace the {{Your-API-Key}} and {{Notice-ID}} parameters with your API key and your notice ID respectively.

Your website will automatically pull the latest configuration based on the notice ID provided.

Supported Web based CTV devices

Devices not included in the supported list are likely compatible. If you encounter any issues with notice rendering on an unsupported device, please contact our support team for assistance.

Below is the list of supported devices:

Tizen OS 3.0 and above
HbbTV 1.5 and above
webOS 4 and above

Configure and interact with the SDK

Once the SDK has loaded, you can call other functions on it to do consent management, send analytics events, etc. To make sure that you use the SDK when it is ready, you can register a global didomiOnReady array of functions that will get called when the SDK is done loading:

<script type="text/javascript">
window.didomiOnReady = window.didomiOnReady || [];
window.didomiOnReady.push(function (Didomi) { 
    // Call other functions on the SDK
});
</script>

onDidomiReady(didomi) {
  console.log('Didomi Ready');
  // Call other functions on the SDK
}

...

<DidomiSDK
    ...
    onReady={this.onDidomiReady.bind(this)}
/>

The SDK exposes other events and functions to allow you to interact programmatically with the CMP. Read our Reference section for more information:

Reference

Didomi Host Element

The Didomi SDK automatically creates a <div> element with the ID didomi-host, where the SDK will render its content. By default, this element is appended at the end of the <body> element of your webpage.

Customization Options

Although we recommend using the default setup, you can optionally create and manage the didomi-host element yourself if your project requires additional control over its configuration. For instance, you may want to adjust the text direction, add custom CSS classes, or modify attributes for accessibility or SEO purposes.

Here is an example of how to manually define the host element:

htmlCopy code<body>
    <div id="didomi-host" class="custom-class"></div>
</body>

Note: Even if you manage the didomi-host element yourself, the SDK will control the following properties to ensure functionality and compliance:

data-nosnippet: Prevents Google from using the CMP UI in search results.
aria-hidden: Ensures the Didomi notice is correctly highlighted for screen readers, improving accessibility.

Best Practices

If you customize the didomi-host element, ensure it is properly styled and positioned to avoid display issues.
Avoid removing or overriding the SDK-managed attributes (data-nosnippet and aria-hidden) to maintain compliance with SEO and accessibility guidelines.

Configure vendors and purposes

As per GDPR, the consent notice collects consents for a specific set of vendors and purposes. You must configure the notice to let it know what vendors are used on your website and it will automatically determine what purposes are required. This can be done from the Didomi Console.

While we interoperate with a lot of vendors through the IAB framework or direct integrations, vendors that do not fall into either of these buckets must be configured through our tag manager or your existing tag manager. Failure to do so will result in vendors not being correctly blocked as needed and you will not be compliant with data privacy regulations.

Read our dedicated section to learn how to configure your vendors.

Add a link for the user to manage their preferences

After the user has given consent or closed the banner, you must given them an easy access to their choices so that they can update them.

You can use the function Didomi.preferences.show() to open the preferences manager and let the user update her choices. Example:

<a href="javascript:Didomi.preferences.show()">Consent preferences</a>

onDidomiReady(didomi) {
    this.didomiObject = didomi;
}

...

<DidomiSDK
    ...
    onReady={this.onDidomiReady.bind(this)}
/>
<button onClick={() => this.didomiObject.preferences.show()}>Consent preferences</button>

We suggest adding this link in your privacy policy or in a header or footer menu on all of your pages.

Didomi supports the IAB Transparency and Consent Framework as well as the IAB CCPA frameworks. Read more in our documentation:

IAB frameworks

PreviousWeb SDK NextTags and vendors management

Last updated 7 months ago