Reference

This section is a comprehensive reference of the methods and events exposed by the SDK and that you can leverage in your application.

__cmp(command, parameter, callback)

Didomi is fully compliant with the CMP API from the IAB Transparency and Consent framework. 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);
});

Read more on the IAB documentation.

getExperiment()

Get the currently configured AB test (experiment) and the user information for that test.

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 group

test if the user is part of the test group

null 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"
}

getObservableOnUserConsentStatusForVendor(vendorId)

Get an observable on the consent status of a specific vendor. By subscribing to the observable, you can define a function that gets called whenever the consent status of a specific vendor changes. 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
}
});

getUserConsentToken()

Return the consent information of the current user formatted as a consent web token. This function will return all the consents that the current user has expressed so far and is useful if you need the full picture. Other functions like getUserConsentStatus give you an easier way to check if a consent has been collected for a specific purpose / vendor.

Parameters

No parameter.

Returns

A consent web token that looks like this:

{
"issuer": "didomi",
"consents": [
{
"purpose": "cookies",
"vendors": ["*", "vendor-name"]
}
]
}

Example

const token = Didomi.getUserConsentToken();

getUserConsentStatus(purpose, vendor)

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

A boolean that indicates if the user has given consent or not.

If you do not apply GDPR to all your visitors, this function will return undefined for visitors that are not subject to GDPR. Use isConsentRequired() to determine whether you can ignore the consent status or not.

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');

getUserConsentStatusForAll()

Get the user consent status for all the purposes and vendors.

Parameters

No parameter.

Returns

An object with all the consent given by the user:

{
"purposes": {
"enabled": ['cookies'],
"disabled": ['analytics'],
},
"vendors": {
"enabled": [1, 2, 3],
"disabled": [4, 5],
}
}

If you do not apply GDPR to all your visitors, this function will return empty arrays for visitors that are not subject to GDPR. Use isConsentRequired() to determine whether you can ignore the consent status or not.

Example

Didomi.getUserConsentStatusForAll();

getUserConsentStatusForPurpose(purposeId)

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.

If you do not apply GDPR to all your visitors, this function will return undefined for visitors that are not subject to GDPR. Use isConsentRequired() to determine whether you can ignore the consent status or not.

Example

Didomi.getUserConsentStatusForPurpose('cookies');

getUserConsentStatusForVendor(vendor)

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.

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

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.

If you do not apply GDPR to all your visitors, this function will return undefined for visitors that are not subject to GDPR. Use isConsentRequired() to determine whether you can ignore the consent status or not.

Example

// IAB vendors
Didomi.getUserConsentStatusForVendor('1');
// Didomi vendors
Didomi.getUserConsentStatusForVendor('vendor-id');
// Custom vendors
Didomi.getUserConsentStatusForVendor('c:custom-vendor-id');

isConsentRequired()

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();

isUserConsentStatusPartial()

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();

notice.isVisible()

Check if the consent notice is currently displayed.

Parameters

No parameter.

Returns

Boolean

Example

Didomi.notice.isVisible();

openTransaction()

Allow you to easily enable/disable a purpose/vendor from the existing consents. It uses setUserConsentStatusForAll under the hood but let you enable/disable a purpose/vendor one by one.

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();

Events

Plain Javascript
React

on(event, fn)

Add an event listener to events raised by the Didomi SDK.

Parameters

Name

Type

Description

event

string

The name of the event type that you want to listen to

fn

Function

The callback function to call when a matching event is raised

Returns

Event listener

Example

Didomi.on('consent.changed', function () {
// Do something when the consent from the user has changed
});
Didomi.on('preferences.clickpurposeagree', function (event) {
// get purposeId : 'event.purposeId'
// Do something when the consent from the user has changed
});

Event types

The following event types are supported by the Didomi SDK:

Name

Description

consent.changed

When a consent is given or withdrawn by the user.

notice.shown

When the notice gets displayed.

Important: This event is usually fired before your callbacks get registered in didomiOnReady so make sure to check if the banner is already visible with notice.isVisible() at least once before registering your event callback.

notice.hidden

When the notice gets closed.

notice.backdropclick

When the backdrop from the popup notice gets clicked

notice.clickagree

When user clicks on agree on the notice

notice.clickmoreinfo

When user clicks on learn more on the notice

preferences.clickagreetoall

When user clicks on agree to all on the preferences popup

preferences.clickdisagreetoall

When user clicks on disagree to all on the preferences popup

preferences.clickpurposeagree

When user agree to a purpose on the preferences popup. (purposeId provided as a parameter)

preferences.clickpurposedisagree

When user disagree to a purpose on the preferences popup. (purposeId provided as a parameter)

preferences.clickviewvendors

When user clicks on view vendors on the preferences popup

preferences.clicksavechoices

When user saves his choice on the preferences popup

preferences.clickvendoragree

When user agree to a vendor on the preferences popup. (vendorId provided as a parameter)

preferences.clickvendordisagree

When user disagree to a vendor on the preferences popup. (vendorId provided as a parameter)

preferences.clickvendorsavechoices

When user saves his choice on the vendors view on the preferences popup

Add an event listener to events raised by the Didomi SDK.

Example

consentHasChanged() {
// Do something when the consent from the user has changed
}
preferencesClickPurposeAgree(purposeId) {
// Do something when user agree on a purpose
}
...
<DidomiSDK
...
onConsentChanged={this.consentHasChanged.bind(this)}
onPreferencesClickPurposeAgree={this.preferencesClickPurposeAgree.bind(this}
/>

Event types

The following event types are supported by the Didomi SDK:

Name

Description

onConsentChanged

When a consent is given or withdrawn by the user.

onNoticeShown

When the notice gets displayed.

onNoticeHidden

When the notice gets closed.

onNoticeBackdropclick

When the backdrop of the popup notice gets clicked

onNoticeClickAgree

When user clicks on agree on the notice

onNoticeClickMoreInfo

When user clicks on learn more on the notice

onPreferencesClickAgreeToAll

When user clicks on agree to all on the preferences popup

onPreferencesClickDisagreeToAll

When user clicks on disagree to all on the preferences popup

onPreferencesClickPurposeAgree

When user agree to a purpose on the preferences popup. (purposeId provided as a parameter)

onPreferencesClickPurposeDisagree

When user disagree to a purpose on the preferences popup. (purposeId provided as a parameter)

onPreferencesClickViewVendors

When user clicks on view vendors on the preferences popup

onPreferencesClickSaveChoices

When user saves his choice on the preferences popup

onPreferencesClickVendorAgree

When user agree to a vendor on the preferences popup. (vendorId provided as a parameter)

onPreferencesClickVendorDisagree

When user disagree to a vendor on the preferences popup. (vendorId provided as a parameter)

onPreferencesClickVendorSaveChoices

When user saves his choice on the vendors view on the preferences popup

preferences.show(view)

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: information, purposes and vendors. (information will only work if you enabled the information view.)

This parameter is optional. If it is not provided, it will display the purposes view or the information view if information is enabled.

Returns

Nothing

Example

Didomi.preferences.show('purposes');

reset()

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();

setUserAgreeToAll()

Report that the user has given consent to all purposes and vendors setup for your website programmatically. This function will log the consent on our platform and close the banner.

Parameters

No parameter.

Returns

Nothing

Example

Didomi.setUserAgreeToAll();

setUserDisagreeToAll()

Report that the user has denied consent to all purposes and vendors setup for your website programmatically. This function will log the consent information on our platform and close the banner.

Parameters

No parameter.

Returns

Nothing

Example

Didomi.setUserDisagreeToAll();

setUserConsentStatusForAll(enabledPurposes, disabledPurposes, enabledVendors, disabledVendors)

Set the user consent status for all the purposes and vendors. You need to pass the full list of enabled/disabled purposes/vendors as it will override the previous consents. To get that list, you can use Didomi.getUserConsentStatusForAll()

Parameters

Name

Type

Description

enabledPurposes

array

The list of IDs of enabled purposes

disabledPurposes

array

The list of IDs of disabled purposes

enabledVendors

array

The list of IDs of enabled vendors

disabledVendors

array

The list of IDs of disabled vendors

Returns

Nothing

Example

Didomi.setUserConsentStatusForAll(
['cookies'],
['analytics'],
[1,2,3],
[4,5],
);

shouldConsentBeCollected()

Determine if consent should be collected for the visitor. Returns true if consent is required for the current user and one of following two conditions is met:

  • Consent has never been collected for this visitor yet

  • New consents should be collected (as new vendors have been added) AND the number of days before recollecting them has exceeded

If none of these two conditions is met, the function returns false. This function is mainly present to allow you to know when to display your own notice if you have disabled our standard notice.

Parameters

No parameter.

Returns

Boolean

Example

Didomi.shouldConsentBeCollected()