API
The Didomi Web SDK exposes a complete API on the page via JavaScript for interacting with the Didomi platform. This allows your scripts to programmatically interact with the Didomi SDK. You can check the user consent status, register consents that you would collect yourself, and show/hide the Didomi UI.
The API is exposed on the
window.Didomi
object. All calls to the Didomi API (except for the standard IAB __cmp
function) must be enclosed within a window.didomiOnReady
callback to ensure that the SDK is ready before calling it: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)}
/>
The
window.didomiOnReady
callbacks are called after the SDK is initialized and has loaded its configuration.Setting
window.didomiConfig
in a window.didomiOnReady
callback has no effect as the SDK is already initialized at that point. window.didomiConfig
must be set at the root of the page and outside of any callback.If your JavaScript is not directly present on the page where the Didomi Web SDK is embedded but is present within an iframe on that page, you can communicate with the Didomi Web SDK through the
postMessage
API of the browser.Currently only
getUserStatus
is exposed via this API to allow reading the consent status of the user. To better understand its usage, you can refer to its definition.The message to send should have the below form where:
command
is the name of the function on thewindow.Didomi
object to callparameter
is an array of parameters passed to the function called on thewindow.Didomi
objectcallId
is a unique value that will be sent back with the response from Didomi, allowing you to identify what call the response is for
window.parent.postMessage({
__cmpCall:
{
command: "*command*",
parameter: [param1, param2, ...],
callId: *uniqueId*
}
}, "*");
The Didomi Web SDK will send back the message below to your frame with the
postMessage
API containing a response for your command where:returnValue
is the value returned by the API function calledsuccess
is a boolean flag indicating whether the call was successful or notcallId
is the unique value provided ascallId
in your original message
{
__cmpReturn:
{
returnValue: *returnValue*,
success: *boolean*,
callId: *uniqueId*
}
}
Here is a complete example of how to call one of the available functions of the postMessage API (
getUserStatus
) and collect its response:window.addEventListener(
"message",
function (event) {
try {
var data = typeof event.data === "string" ? JSON.parse(event.data) : event.data;
if (data && data.__cmpReturn) {
// data.__cmpReturn contains the response from the CMP
if (data.__cmpReturn.callId === "get-user-status") {
// This is the response to our call for getting the user status
// The status is in data.__cmpReturn.returnValue
// Do something
}
}
} catch(e) {
// An error happened when decoding the message data
// Most likely, the message wasn't related to the CMP so do nothing
}
},
false
);
​
window.parent.postMessage({
__cmpCall:
{
command: "getUserStatus",
parameter: [],
callId: "get-user-status"
}
}, "*");
The frame to send the
postMessage
to can be determined by the ancestor with a .frames["cmpLocator"]
child iframe present.If your code runs in a direct iframe of the page containing the
window.Didomi
object then you can simply use window.parent as the reference to send messages to.If your code might run multiple levels removed from the frame containing the
window.Didomi
object, you can search for the correct frame to send a message to with the following code:var f = window;
var cmpFrame;
​
while(!cmpFrame) {
try {
if(f.frames["__cmpLocator"]) cmpFrame = f;
} catch(e) {}
​
if(f === window.top) break;
​
f = f.parent;
}
Parameters
No parameter.
Returns
An object with the following properties:
Name | Type | Description |
id | string | ID of the experiment as configured in your tag |
group | string | Group that the user is assigned to for the experiment control if the user is part of the control grouptest if the user is part of the test groupnull if the user is not part of the experiment |
size | number | Size of the test group (number between 0 and 1) |
startDate | string | Start date of the test as ISO 8601 with millisecond precision |
Example
{
"id": "experiment-id",
"group": "control",
"size": 0.1,
"startDate": "2019-03-06T23:38:50.000Z"
}
Check if a given regulation applies to the current user.
Parameters
Name | Type | Description |
regulation | string | gdpr for GDPRccpa for CCPA |
Returns
A
boolean
indicating whether the user is subject to the regulation and support for the regulation is enabled for the website.Example
if (Didomi.isRegulationApplied('gdpr')) {
// The user is subject to GDPR, do something
}
​
if (Didomi.isRegulationApplied('ccpa')) {
// the user is subject to CCPA, do something
}
Simulate a user input by indicating to the SDK that the user has pressed a button on an input device like a keyboard or a TV remote control. This function is usually called when mapping TV remote control inputs to the Didomi SDK.
This function is only available if the TV mode of the SDK is enabled by adding the following
didomiConfig
to your page:window.didomiConfig = {
mode: 'tv' // Enable TV mode
};
window.didomiConfig
must be set outside of any callback like window.didomiOnReady
to be effective.If no UI view is displayed from the Didomi SDK (notice, purposes, or vendors), this function has no effect and will log an error message that can be ignored.
Parameters
Name | Type | Description |
button | string | The button that was pressed by the user. See below for the acceptable values for this parameter. |
The
button
parameter can take one of the following values:Value | Description |
confirm | When the user presses a confirmation button (like OK or Enter). This input validates the user choice when pressed on UI buttons like Agree or Disagree. |
cancel | When the user presses a cancellation button (like Return or Exit). This input cancels the current action and, usually, closes the current UI view. |
up | When the user presses a button to move up (like an Up arrow). This input moves the focus to the closest action button located above the current focused element. If no such input exists, the focus is moved to the last element of the current UI view. |
right | When the user presses a button to move right (like a Right arrow). This input moves the focus to the closest action button located to the right of the current focused element. If no such input exists, the focus is moved to the next element of the current UI view. |
down | When the user presses a button to move down (like a Down arrow). This input moves the focus to the closest action button located below the current focused element. If no such input exists, the focus is moved to the first element of the current UI view. |
left | When the user presses a button to move left (like a Left arrow). This input moves the focus to the closest action button located to the left of the current focused element. If no such input exists, the focus is moved to the previous element of the current UI view. |
Returns
No return value.
Example
Didomi.navigate('down');
Didomi.navigate('confirm');
Check if the consent notice is currently displayed.
Parameters
No parameter.
Returns
Boolean
Example
Didomi.notice.isVisible();
Show the preferences manager. This can be used to allow the user to update their consent choices after the notice has been closed. We suggest adding a link with this function call somewhere on your website.
Parameters
Name | Type | Description |
view | string | The view you want to open. Possible options for GDPR: information, purposes and vendors . (information will only work if you enabled the information view).
For CCPA, the Do Not Sell view is always open.
This parameter is optional. If it is not provided, it will display the purposes view or the information view if information is enabled for GDPR. |
Returns
Nothing
Example
Didomi.preferences.show('purposes');
Reset all the consent information for the current user and assign a new user ID. This will remove all cookies created by Didomi and will trigger re-collection of consent. The consent notice will be displayed again.
Parameters
No parameter.
Returns
Nothing
Example
Didomi.reset();
Didomi is fully compliant with the CMP API from the IAB Transparency and Consent framework version 1.
We expose a
__cmp
function and listen to postMessage
events as per the specification.Example (getting the IAB consent string):
__cmp('getConsentData', null, function (result) {
// The IAB consent string is available in the `consentData` property of the object
console.log(result.consentData);
});
The __cmp function belongs to the IAB Transparency and Consent framework version 1, which is officially deprecated since 8/15/2020.
Didomi is fully compliant with the CMP API from the IAB Transparency and Consent framework version 2.
We expose a
__tcfapi
function and listen to postMessage
events as per the specification.Example (getting the IAB consent string):
__tcfapi('getTCData', null, function(result) {
// The IAB consent string is available in the `tcString` property of the object
console.log(result.tcString);
});
Get an observable on the consent status for a given vendor. By subscribing to the observable, you can define a function that gets called whenever the consent status of a given vendor changes.
We use the list of purposes declared for the vendor to make sure that it has consent for all of them. The required purposes are automatically setup for IAB or Didomi vendors and you must specify the required purposes for your custom vendors when configuring the tag.
It also allows you to filter for specific types of updates so that you can react to certain events only. It is an alternative to listening to the
consent.changed
event that helps in dealing with vendor-specific operations.This is commonly used to observe the consent status for a vendor to decide when to load/enable the vendor on a page.
Parameters
Name | Type | Description |
vendor | string | The ID of vendor that to check the user consent for. If you are checking an IAB vendor, use an integer instead of a string. Custom vendor IDs must be prefixed with c: . |
Returns
Observable
on the consent status of the vendor.The observable is not a real RxJS observable and only supports the following operators: distinctUntilChanged, filter and first. These operators behave the same as in RxJS.
Examples:
Example 1 - Get all updates to the consent status for a vendor
With this structure, your function gets called when the user gets on the page and every time the consent status of the user changes.
Didomi.getObservableOnUserConsentStatusForVendor('vendor-id')
.subscribe(function (consentStatus) {
if (consentStatus === undefined) {
// The consent status for the vendor is unknown
} else if (consentStatus === true) {
// The user has given consent to the vendor
} else if (consentStatus === false) {
// The user has denied consent to the vendor
}
});
Example 2 - Get updates when the consent status is true or false
With this structure, your function only gets called after the user has given consent information. It could be on page load if the user had already given consent on a previous page or every time the user interacts with the Didomi widgets to change their consent information. When the consent status is unknown, your function does not get called.
Didomi.getObservableOnUserConsentStatusForVendor('vendor-id')
.filter(function (status) { return status !== undefined })
.subscribe(function (consentStatus) {
if (consentStatus === undefined) {
// The consent status for the vendor is unknown
} else if (consentStatus === true) {
// The user has given consent to the vendor
} else if (consentStatus === false) {
// The user has denied consent to the vendor
}
});
Example 3 - Get the first update to the consent status of the vendor
With this structure, your function gets called exactly once with the first available consent status. If the user has not given consent yet, your function will get called with
undefined
. If the user has already given consent, your function will get called with the consent status from the user.Didomi.getObservableOnUserConsentStatusForVendor('vendor-id')
.first()
.subscribe(function (consentStatus) {
if (consentStatus === undefined) {
// The consent status for the vendor is unknown
} else if (consentStatus === true) {
// The user has given consent to the vendor
} else if (consentStatus === false) {
// The user has denied consent to the vendor
}
});
Example 4 - Get the first true or false update to the consent status of the vendor
With this structure, your function gets called exactly once when the consent status becomes available. If the user has not given consent yet, your function will only be called after the user has given consent. If the user has already given consent, your function will immediately get called with the consent status from the user. Your function will never get called with
undefined
.Didomi.getObservableOnUserConsentStatusForVendor('vendor-id')
.first()
.filter(function(status) { return status !== undefined; })
.subscribe(function (consentStatus) {
if (consentStatus === true) {
// The user has given consent to the vendor
} else if (consentStatus === false) {
// The user has denied consent to the vendor
}
});
Get the list of purpose IDs that are configured for the consent notice and that consent is collected for.
Parameters
No parameter.
Returns
An array of purpose IDs.
Example
// Returns ['cookies']
Didomi.getRequiredPurposeIds();
Get the list of vendor IDs that are configured for the consent notice and that consent is collected for.
Parameters
No parameter.
Returns
An array of vendor IDs.
Example
// Returns ['google']
Didomi.getRequiredVendorIds();
Search the purpose in
getUserStatus().purposes.global.enabled
or getUserStatus().purposes.global.disabled, and the vendor in getUserStatus().vendors.global.enabled
or getUserStatus().vendors.global.disabled
.Check if the current user has given consent for a specific purpose and vendor.
Parameters
Name | Type | Description |
purpose | string | The purpose that we are checking the user consent for (example: cookies ) |
vendor | string | The ID of vendor whose user consent is being checked for. If you are checking an IAB vendor, use an integer instead of a string. Custom vendor IDs must be prefixed with "c:" . |
Returns
A
boolean
that indicates if the user has given consent or not.The method always returns
true
if the specified purpose is an essential purpose and if the specified vendor has consent.Example
// IAB vendors
Didomi.getUserConsentStatus(Didomi.Purposes.Cookies, '1');
​
// Didomi vendors
Didomi.getUserConsentStatus(Didomi.Purposes.Cookies, 'vendor-id');
​
// Custom vendors
Didomi.getUserConsentStatus(Didomi.Purposes.Cookies, 'c:custom-vendor-id');
Search the purposeId in
getUserStatus().purposes.global.enabled or getUserStatus().purposes.global.disabled.
Get the user consent status for a given purpose.
Parameters
Name | Type | Description |
purposeId | string | The ID of purpose that to check the user consent for. |
Returns
A
boolean
that indicates if the user has given consent or not to the specific purpose.undefined
is returned if the consent status is not known yet. From a GDPR perspective, you'll want to treat undefined
as false
(ie no consent given) but it is helpful to know that the user has not interacted with the consent UI yet so that you can subscribe to events and wait for consent information to be collected.The method always returns
true
if the specified purpose is an essential purpose.Example
Didomi.getUserConsentStatusForPurpose('cookies');
Search the vendorId in
getUserStatus().vendors.consent.enabled
or getUserStatus().vendors.consent.disabled
.
Get the user consent status for a given vendor. We use the list of purposes declared for the vendor to make sure that it has consent for all of them. The required purposes are automatically setup for IAB or Didomi vendors and you must specify the required purposes for your custom vendors when configuring the tag.
When determining user consent status for a given vendor, the method will treat essential purposes as purposes with given consent.
Parameters
Name | Type | Description |
vendor | string | The ID of the vendor whose user consent is being checked for. If you are checking an IAB vendor, use an integer instead of a string. Custom vendor IDs must be prefixed with c: . |
Returns
A
boolean
that indicates if the user has given consent or not to the specific vendor and all the purposes that require consent for that vendor.undefined
is returned if the consent status is not known yet. From a GDPR perspective, you'll want to treat undefined
as false
(ie no consent given) but it is helpful to know that the user has not interacted with the consent UI yet so that you can subscribe to events and wait for consent information to be collected.Example
// IAB vendors
Didomi.getUserConsentStatusForVendor('1');
​
// Didomi vendors
Didomi.getUserConsentStatusForVendor('vendor-id');
​
// Custom vendors
Didomi.getUserConsentStatusForVendor('c:custom-vendor-id');
Get the user consent and legitimate interest status for all the purposes and vendors.
Parameters
No parameter.
Returns
An object with the consent and legitimate interest status of the user for every purpose and vendor. The response also contains the user ID from Didomi (
user_id
), the TCF consent string (consent_string
), additional consent string from Google's additional consent mode (addtl_consent
) and the dates of the user choices (created
and updated
ISO8061 dates).It returns an object with the following information:
- Consent and LI status for purposes
- Consent and LI status for vendors
- Computed global status for vendors (based on the required purposes for that vendor)
- User ID
- TCF consent string
- Additional consent string
- User creation date
- User update date
- User sync date
{
purposes: {
global: {
enabled: ['purpose1'], // IDs of the purposes that are essential OR enabled as consent OR enabled as LI
disabled: ['purpose2'] // All other purposes
},
consent: {
enabled: ['purpose1'], // IDs of the purposes with consent enabled
disabled: ['purpose2'] // IDs of the purposes with consent disabled
},
legitimate_interest: {
enabled: ['purpose1'], // IDs of the purposes with legitimate interest enabled
disabled: ['purpose2'] // IDs of the purposes with legitimate interest disabled
},
essential: ['purposexxx'], // IDs of the purposes that are defined as essential
},
vendors: {
consent: {
enabled: ['vendor1'], // IDs of the vendors with consent enabled
disabled: ['vendor2'] // IDs of the vendors with consent disabled
},
legitimate_interest: {
enabled: ['vendor1'], // IDs of the vendors with legitimate interest enabled
disabled: ['vendor2'] // IDs of the vendors with legitimate interest disabled
},
global: {
enabled: ['vendor1'], // IDs of the vendors that have been marked as enabled by the user based on consent/LI. When computing this property, required purposes are taken into account and essential purposes are considered as enabled.
disabled: ['vendor2'] // All other vendors
},
global_consent: {
enabled: ['vendor1'], // IDs of the vendors that have been marked as enabled by the user based on consent. When computing this property, required purposes are taken into account and essential purposes are considered as enabled.
disabled: ['vendor2'] // All other vendors
},
global_li: {
enabled: ['vendor1'], // IDs of the vendors that have been marked as enabled by the user based on LI. When computing this property, required purposes are taken into account and essential purposes are considered as enabled.
disabled: ['vendor2'] // All other vendors
}
},
user_id: 'user_id_from_token', // Didomi user ID
created: 'ISO8061 creation date from token', // User choices creation date
updated: 'ISO8061 update date from token', // User choices update date
consent_string: '...' // TCF consent string,
addtl_consent: '...' // Additional consent string
}
Example
Didomi.getUserStatus();
Determine if consent is required for the user based on two rules:
- You are an EU company and collect consent for all visitors. In that case, consent is always required.
- You are not an EU company and you only need to collect consent for EU visitors (see Country and GDPR for more information). In this case, we use the geolocation of the user to determine whether GDPR applies or not. For instance, a user in France or Germany will require consent (under the GDPR) whereas a user in the United States will not.
If you do not apply GDPR to all your visitors, you should call this function to determine whether you need to condition the loading of vendors or not.
Parameters
No parameter.
Returns
Boolean
Example
Didomi.isConsentRequired();
Determine if all consent information is available for the user.
This function returns
true
if and only if:- Consent is required for the user (ie the user is in the EU or your tag is configured to apply GDPR to all users)
- At least one vendor is configured (if there is no vendor configured, this function always returns
false
as there is no consent to collect) - We are missing consent information for at least one vendor or purpose.
- The consent re-collection window as configured in your tag has expired.
If there is at least one piece of consent information missing for a single vendor/purpose, this function will return
true
. The consent notice is usually displayed when this function returns true
although there is no guarantee of the direct mapping between the two.An important edge case is when you add new vendors or if configured vendors ask for new purposes: the consent notice will be displayed again and this function will return
true
until the user has given or denied consent. Vendors that already had consent before will still operate normally as we only recollect consent for additional vendors/purposes.Parameters
No parameter.
Returns
Boolean
Example
Didomi.isUserConsentStatusPartial();
Allow you to easily enable/disable a purpose/vendor from the existing consents.
Parameters
No parameter.
Returns
a
Transaction
object that contain the current consents. You can then modify them with the functions below.Example
const transaction = Didomi.openTransaction();
// enable a purpose
transaction.enablePurpose('cookies');
// enable purposes
transaction.enablePurposes('cookies', 'analytics');
// disable a purpose
transaction.disablePurpose('analytics');
// disable purposes
transaction.disablePurposes('cookies', 'analytics');
// enable a vendor
transaction.enableVendor(1);
// enable vendors
transaction.enableVendors(2, 3);
// disable a vendor
transaction.disableVendor(2);
// disable vendors
transaction.disableVendors(2, 3);
// Save and set the token/cookie with the new values
transaction.commit();
Report that the user has enabled consents and legitimate interests for all purposes and vendors configured for your website.
This function will log the user choice on our platform and close the notice.
Consent statuses for essential purposes are not stored.
Read our detailed section to see how essential purposes behave and how to configure them.
Please read our article on what to expect from your analytics when setting a custom behavior for your consent notice.
Parameters
No parameter.
Returns
Nothing
Example
Didomi.setUserAgreeToAll();
Report that the user has disabled consents and legitimate interests for all purposes and vendors configured for your website.
This function will log the user choice on our platform and close the notice.
Consent statuses for essential purposes are not stored.
Read our detailed section to see how essential purposes behave and how to configure them.
Please read our article on what to expect from your analytics when setting a custom behavior for your consent notice.
Parameters
No parameter.
Returns
Nothing
Example
Didomi.setUserDisagreeToAll();
Sets the user consent and legitimate interest statuses for vendors and purposes. You must pass the full list of enabled/disabled purposes/vendors as it will override the previous consent and legitimate interest statuses. To get the current user status, you can use
Didomi.getUserStatus()
Please read our article on what to expect from your analytics when setting a custom behavior for your consent notice.
Parameters
Parameters is an object with the following structure:
Name | Type | Description |
purposes.consent.enabled | array | The list of IDs of purposes enabled for the consent legal basis |
purposes.consent.disabled | array | The list of IDs of purposes disabled for the consent legal basis |
purposes.legitimate_interest.enabled | array | The list of IDs of purposes enabled for the legitimate interest legal basis |
purposes.legitimate_interest.disabled | array | The list of IDs of purposes disabled for the legitimate interest legal basis |
vendors.consent.enabled | array | The list of IDs of vendors enabled for the consent legal basis |
vendors.consent.disabled | array | The list of IDs of vendors disabled for the consent legal basis |
vendors.legitimate_interest.enabled | array | The list of IDs of vendors enabled for the legitimate interest legal basis |
vendors.legitimate_interest.disabled | array | The list of IDs of vendors disabled for the legitimate interest legal basis |
created | ISO8601 date | An optional ISO8601 date which represents the date when the consent was created |
updated | ISO8601 date | An optional ISO8601 date which represents the date when the consent was last updated |
action | string | Action which triggered user status change |
Returns
Nothing
Example
Didomi.setUserStatus({
purposes: {
consent: {
enabled: ['purpose1'], // IDs of the purposes with consent enabled
disabled: ['purpose2'] // IDs of the purposes with consent disabled
},
legitimate_interest: {
enabled: ['purpose1'], // IDs of the purposes with legitimate interest enabled
disabled: ['purpose2'] // IDs of the purposes with legitimate interest disabled
}
},
vendors: {
consent: {
enabled: ['vendor1'], // IDs of the vendors with consent enabled
disabled: ['vendor2'] // IDs of the vendors with consent disabled
},
legitimate_interest: {
enabled: ['vendor1'], // IDs of the vendors with legitimate interest enabled
disabled: ['vendor2'] // IDs of the vendors with legitimate interest disabled
}
}
});
Sets the user consent and legitimate interest statuses for all vendors and purposes. This method overrides the previous consent and legitimate interest statuses. To get the current user status, you can use
Didomi.getUserStatus()
Please read our article on what to expect from your analytics when setting a custom behavior for your consent notice.
Parameters
Parameters is an object with the following structure:
Name | Type | Description |
purposesConsentStatus | boolean | Boolean value specifying whether all purposes' consents should be enabled or disabled |
purposesLIStatus | boolean | Boolean value specifying whether all purposes' legitimate interests should be enabled or disabled |
vendorsConsentStatus | boolean | Boolean value specifying whether all vendors' consents should be enabled or disabled |
vendorsLIStatus | boolean |