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. Place the following tag at the top of the <head> section of your HTML pages, before any other script tag:

<script type="text/javascript">
window.gdprAppliesGlobally=true;
(function(){function n(){if(!window.frames.__cmpLocator){if(document.body&&document.body.firstChild){var e=document.body;var t=document.createElement("iframe");t.style.display="none";t.name="__cmpLocator";e.insertBefore(t,e.firstChild)}else{setTimeout(n,5)}}}function e(e,t,n){if(typeof n!=="function"){return}if(!window.__cmpBuffer){window.__cmpBuffer=[]}if(e==="ping"){n({gdprAppliesGlobally:window.gdprAppliesGlobally,cmpLoaded:false},true)}else{window.__cmpBuffer.push({command:e,parameter:t,callback:n})}}e.stub=true;function t(a){if(!window.__cmp||window.__cmp.stub!==true){return}if(!a.data){return}var r=typeof a.data==="string";var e;try{e=r?JSON.parse(a.data):a.data}catch(t){return}if(e.__cmpCall){var i=e.__cmpCall;window.__cmp(i.command,i.parameter,function(e,t){var n={__cmpReturn:{returnValue:e,success:t,callId:i.callId}};a.source.postMessage(r?JSON.stringify(n):n,"*")})}}if(typeof window.__cmp!=="function"){window.__cmp=e;if(window.addEventListener){window.addEventListener("message",t,false)}else{window.attachEvent("onmessage",t)}}n()})();
</script>
<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
all: true
}
}
}
};
</script>
<script type="text/javascript" id="spcloader" src="https://sdk.privacy-center.org/loader.js" async></script>

Make sure to:

  • Place the tag as close to the opening <head> tag on your page as possible, before any other tag gets embedded

  • Add your API key into the tag (replace the <Your API Key> value)

  • Configure the gdprAppliesGlobally variable to false if you are not an EU-based company and only want to collect consent from EU visitors

Important: Embed our tag before any other tag

Yes, it's so important that we say it more than 4 times on this page!

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.

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

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

const didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
all: true
}
}
}
}
...
<DidomiSDK
config={didomiConfig}
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')}
/>

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

Display the notice

This will display our standard banner to all visitors, collecting consent for all the IAB vendors (more on this later, for now, just keep in mind that if you remove the vendors property, no banner will be displayed as the banner will consider that there is no consent to collect). Keep reading to see what configuration options you can use to customize the banner.

Also keep in mind that, 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. Read our documentation on this topic.. Failure to do so will result in vendors not being correctly blocked as needed and you will not be compliant with GDPR.

Loading optimization

The SDK is loaded as an async JavaScript resource which ensures that it executes asynchronously while the page is being parsed and the other resources loaded. That way, it will have a minimal impact on your page load time and your content.

Fully compliant with the IAB GDPR framework

The notice is fully compliant with the IAB GDPR framework and will share the consent information collected from users with third-parties adhering to this framework to let them know what processing they are allowed to run. We also offer options to control the loading of third-party tags through your tags managers or special script tags.

Not collecting consent for non EU visitors

The banner should display to all users no matter where they are located. If you are a non EU-based company then you are only required to collect consent and show the banner to EU visitors and can configure the banner to do so by changing the gdprAppliesGlobally variable to false in the tag above (that variable is separate from the window.didomiConfig variable).

Please note that if you are an EU-based company then you must collect consent and display the banner to all visitors, no matter where they are from.

Testing from outside the UE

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 app.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%3Aapp.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%3Aapp.ignoreCountry=true and the notice should be displayed even if you are not in the EU.

Configure your website name and logo

The name of your website (or company) is used to customize our default messages. Your logo should also be added as it helps the user understand who they are giving consent to.

Set the app.name and app.logoUrl properties to configure your website name and logo:

Plain Javascript
React
<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
}
}
};
</script>
const didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
}
}
};
...
<DidomiSDK config={didomiConfig}/>

Configure your supported languages (optional)

Our SDK supports multiple European languages out-of-the-box with translations for all our standard messages. English is the default language: if a visitor does not use a supported language, the banner and popups will be displayed in English.

You do not need to do anything to use Didomi's languages. However, you can choose to enable only certain languages and set up a different default language. Set the languages.enabled property to your list of supported languages and languages.default property as the default language in case the customer language is not supported:

Plain Javascript
React
<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
},
languages: {
enabled: ['en', 'fr', 'es'], // List of languages that visitors can use (must be a subset of the languages that we support)
default: 'fr', // Default language to use if the visitor uses a language that is not enabled
}
};
</script>
const didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
},
languages: {
enabled: ['en', 'fr', 'es', 'nl', 'ca', 'it', 'de', 'pt', 'hr'], // List of languages that visitors can use (must be a subset of the languages that we support)
default: 'fr', // Default language to use if the visitor uses a language that is not enabled
}
};
...
<DidomiSDK config={didomiConfig}/>

By default, enabled is the list of supported languages by Didomi and default is en.Currently we support all the European languages and provide standard translations for them. Here is the list of supported languages. You can support different languages by changing the English texts and setting English as the only enabled language.

Add your privacy policy URL

Our default text includes a link to your privacy policy. You can set that URL with the app.privacyPolicyURL property :

Plain Javascript
React
<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
privacyPolicyURL: 'https://privacy.didomi.io/'
}
};
</script>
const didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
privacyPolicyURL: 'https://privacy.didomi.io/'
}
};
...
<DidomiSDK config={didomiConfig}/>

Customize the consent notice

We offer further configuration options to customize the notice for your website. For instance, you can pretty easily change the colors of the notice and the buttons by setting the theme's primary color:

Plain Javascript
React
<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
privacyPolicyURL: 'https://privacy.didomi.io/'
},
theme: {
color: '#BD081C'
}
};
</script>
const didomiConfig = {
app: {
apiKey: '<Your API key>',
name: 'Your website name',
logoUrl: 'https://url-to-your-logo/',
vendors: {
iab: {
all: true
}
},
privacyPolicyURL: 'https://privacy.didomi.io/'
},
theme: {
color: '#BD081C'
}
};
...
<DidomiSDK config={didomiConfig}/>

The theme color will be applied to both the consent notice and the policy so you don't have to manually specify every background or text color.

You can also customize the shape and position of the notice and much more. Read the Customization section to get more information on the configuration options of the notice.

Configure and interact with the SDK

Once the SDK has loaded, you can call other functions on it to do consent management, integrate with the privacy center, 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:

Plain Javascript
React
<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)}
/>

Configure vendors and purposes

As per the regulation, 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.

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

If you are installing Didomi through one of our partners, the consent notice might already be pre-configured with some vendors. You can add more to the list to make sure that all your vendors are included but you will not be able to override those pre-set 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:

Plain Javascript
React
<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.

CMP API (IAB GDPR framework)

Didomi is a registered CMP (ID 7) with the IAB. We fully support the CMP API and your vendors will automatically use the __cmp function that we expose to collect user consent.

Read more on the IAB documentation.

What's next?

There is plenty more to customize on our banner, read the following sections for more information: