API
Usage
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.
Didomi ready
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:
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.
postMessage API
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.
Available functions
Currently only getCurrentUserStatus
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.
Messages structure
The Didomi API is exposed with the same structure as the IAB CMP API.
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
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
Usage example
Here is a complete example of how to call one of the available functions of the postMessage API (getCurrentUserStatus
) and collect its response:
Determining the frame containing the Didomi CMP
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:
Notice config
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:
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
isRegulationApplied(regulation)
Check if a given regulation applies to the current user.
Parameters
regulation
string
gdpr
for GDPR
ccpa
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
navigate(button)
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
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:
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
notice.isVisible()
Check if the consent notice is currently displayed.
Parameters
No parameter.
Returns
Boolean
Example
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
view
string
The view you want to 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
User status
addVendorStatusListener
Definition
Listens to the user’s status for a given vendor and returns a callback when the status changes.
Parameters
Vendor ID
string
The ID of the vendor for which the changes will be tracked by the function.
This ID must be the Didomi API ID, with no prefixes (for example:
google
).
callback
function
Callback that will be executed whenever changes are detected on the specified vendor.
Returns
Numeric value indicating the index position of the listener (zero-based indexing) in the list of registered listeners.
Example
clearUser()
Clear the user configuration details set via setUser
or window.didomiConfig.user
in a single-page application. This function does not clear the local user status (use reset()
for that).
If your website is not a single-page application, do not use this function and stop setting the user configuration details via window.didomiConfig.user
on page load instead.
Parameters
No parameter.
Returns
Promise<void>
Example
getCurrentUserStatus()
Definition
Exposes the user status for the current regulation that applies.
Parameters
No parameters.
Returns
The user status containing the computed global status for Vendors and purposes:
A vendor's global status is enabled, if and only if:
the vendor is enabled directly in the vendors layer in all legal basis
AND all its related purposes are enabled or essential.
A purpose's global status is enabled in one of the two conditions:
the purpose is enabled for all the legal basis that it is configured for.
OR when the purpose is essential.
vendors
object
Object that maps the ID of a vendor to an object representing its status.
Vendors with undefined user status are included in the response with
enabled: false.
Vendors with ONLY essential purposes are automatically set with
enable: true
purposes
object
Object that maps the ID of a purpose to an object representing its status.
Purposes with undefined user status are included in the response with
enabled: false.
Essential purposes are automatically set with
enable: true
regulation
string
Representation of the current regulation as a
Regulation
enum value, such asGDPR
,CCPA
,CPRA
, orNONE
.Note that some regulations present as enum values are not available yet.
userId
string
Didomi user id.
created
string
User choices creation date.
updated
string
User choices update date.
consentString
string
TCF consent as string
additionalConsent
string
Additional consent.
Example
getRequiredPurposeIds
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
getRequiredVendorIds
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
isUserStatusPartial()
This function assesses whether the user has made choices regarding all the vendors and data processing tasks specified by the regulation. It returns true
if there are any vendors or data processing activities for which the user has yet to express a preference.
Requires SDK to be initialized.
Parameters
No parameter.
Returns
Boolean
The function returns true
when the following conditions are all met:
A relevant regulation applies to the current user, meaning the regulation is not classified as
none
.There is at least one vendor configured. Without any configured vendors, the function defaults to
false
since there are no statuses to evaluate.There is a lack of user status for certain vendors or for specific purposes.
In all other scenarios, the function will return false
.
For example, when the regulation is set to none
, indicating that no specific regulation is applicable to the end-user, the function will yield false
.
An important edge case to consider is when a new vendor is introduced to the system and their status has not yet been collected. In such instances, the function will return true
until the user updates their preferences through the notice banner.
Example
openCurrentUserStatusTransaction
Create an instance of the CurrentUserStatusTransaction
object.
This object provides mechanisms to stage updates to the user status regarding purposes and vendors, allowing for batch operations.
Updates made through its methods are queued and applied simultaneously to the user status only once the commit
method of the returned object is called.
Additional notes:
The status of vendors and purposes whose IDs are not not specified through the methods provided by
CurrentUserStatusTransaction
are kept unchanged.Essential purposes are always set to enabled and can’t be updated by the methods provided by
CurrentUserStatusTransaction
.When the regulation applied for a user is
none
, the methods provided byCurrentUserStatusTransaction
should not update the status of any vendor or purpose which will always remain as enabled. When thecommit
method is called it will returnfalse
.If the IDs that are passed through the methods provided by
CurrentUserStatusTransaction
don’t correspond to vendors or purposes required by the Notice Config, they will be ignored.
Parameters
No parameter.
Returns
An instance of the CurrentUserStatusTransaction
object.
enablePurpose
id
(string
): ID of the purpose to be enabled.
Current CurrentUserStatusTransaction
object.
Enable a single purpose based on its ID.
enablePurposes
ids
([string]
): IDs of the purposes to be enabled.
Current CurrentUserStatusTransaction
object.
Enable multiple purposes based on their IDs.
disablePurpose
id
(string
): ID of the purpose to be disabled.
Current CurrentUserStatusTransaction
object.
Disable a single purpose based on its ID.
disablePurposes
ids
([string]
): IDs of the purposes to be disabled.
Current CurrentUserStatusTransaction
object.
Disable multiple purposes based on their IDs.
enableVendor
id
(string
): Didomi ID of the vendor to be enabled.
Current CurrentUserStatusTransaction
object.
Enable a single vendor based on its Didomi ID.
enableVendors
ids
([string]
): Didomi IDs of the vendors to be enabled.
Current CurrentUserStatusTransaction
object.
Enable multiple vendors based on their Didomi IDs.
disableVendor
id
(string
): Didomi ID of the vendor to be disabled.
Current CurrentUserStatusTransaction
object.
Disable a single vendor based on its Didomi ID.
disableVendors
ids
([string]
): Didomi IDs of the vendors to be disabled.
Current CurrentUserStatusTransaction
object.
Disable multiple vendors based on their Didomi IDs.
commit
No parameters.
true
if user status has been updated, false
otherwise.
Commit the changes that have been made through other methods.
Examples
Error handling
Invalid purposes or vendors will be ignored, errors will be logged in the browser's console
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
setUser(userConfiguration)
Update the user configuration details in a single-page application. You can provide the user configuration options as part of the userConfiguration
parameter.
If your website is not a single-page application, do not call this function and set the user configuration details via window.didomiConfig.user
on page load instead.
The setUser
function will update all the provided properties and set the others to undefined
. If a property is omitted, it will be set to undefined
.
Parameters
userConfiguration
object
An object containing any of the following properties:
organizationUserId
: Organization User ID to associate with the user
organizationUserIdAuthAlgorithm
: Algorithm used for computing the digest
organizationUserIdAuthSid
: ID of the secret used for computing the digest
organizationUserIdAuthSalt
: Salt used for computing the digest
organizationUserIdAuthDigest
: Digest of the organization user ID and secret
organizationUserIdExp
: Unix timestamp
organizationUserIdIv
: If encryption is used and an IV was used for encrypting the message
Returns
Nothing
Example
setUserAgreeToAll()
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
setUserDisagreeToAll()
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
setCurrentUserStatus(parameters)
Definition
Set the user status for purposes and vendors. This function will trigger events and API calls every time it is called (and the user status changes) so make sure to push all user choices at once and not one by one.
Please read our article on what to expect from your analytics when setting a custom behavior for your consent notice.
Parameters
Add the desired global status for each vendor and each purpose:
the vendor status specified in this function will be reflected on the vendor’s layer.
vendor enabled : true → means the vendor is enabled in all the legal basis that this vendor uses.
vendor enabled : false → means the vendor is disabled in all the legal basis that this vendor uses
the purposes status specified in this function will be reflected on the preferences layer.
purpose enabled : true → means the purpose is enabled in all the legal basis in which it’s defined.
purpose enabled : false → means the purpose is disabled in all the legal basis in which it’s defined.
Returns
boolean
true
if the user choices have changed (i.e. the user had made different choices before this function got called).
Example
setWidgetLocale()
This function is only supported by Privacy widgets.
Definition
Set the language for a widget.
Parameters
Widget ID
String
The identifier for the widget.
Locale
String
Example
shouldUserStatusBeCollected()
Determine if user status (consent) should be collected for the visitor. Returns true
if user status is required for the current user and one of following two conditions is met:
User status has never been collected for this visitor yet
New user status should be collected (as new vendors have been added) AND the number of days before recollecting them has exceeded
The ignoreConsentBefore flag has been set with a date that applies to force consent renewal
If none of these 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
syncUser()
Update the local user status from the server in a single-page application if the server has a more recent user status than the local one.
If your website is not a single-page application, do not call this function as syncing will be done automatically when the the user configuration details are set via window.didomiConfig.user
on page load.
The synchronization only runs if the following conditions are met: synchronization is enabled in the configuration, an organization user ID has been provided for the user, the user is not a bot, and the sync frequency has not been exceeded.
Parameters
No parameter.
Returns
A promise that resolves when the user status has been synced with the server:
A SyncReadyEvent
is provided as the return value of the function with the following properties:
statusApplied
boolean
Indicates if the user status has been applied locally from the remote Didomi backend. true
if the user status was applied from the remote, false
otherwise.
syncAcknowledged
Function
Callback that can be used to communicate to the Didomi servers that the synchronization has been communicated to the user. Returns true
if the API event was successfully sent, false
otherwise.
syncError
undefined | string
An error message if the sync failed
Example 1 - Simple sync
Example 2 - Reassurance notice
GDPR
__tcfapi(command, version, callback, parameter)
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):
Last updated