Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
      • Versions
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page
  • GDPR
  • __cmp(command, parameter, callback)
  • getObservableOnUserConsentStatusForVendor(vendorId)
  • getUserConsentStatus(purpose, vendor)
  • getUserConsentStatusForPurpose(purposeId)
  • getUserConsentStatusForVendor(vendor)
  • getUserStatus()
  • isConsentRequired()
  • isUserConsentStatusPartial()
  • openTransaction()
  • setUserStatus(parameters)
  • setUserStatusForAll(params)
  • shouldConsentBeCollected()
  • CCPA
  • setDoNotSellStatus(status)
  • getDoNotSellStatus()
  1. SDKs
  2. Web SDK
  3. Reference
  4. API

Deprecated

PreviousAPINextEvents

Last updated 11 months ago

GDPR

__cmp(command, parameter, callback)

Didomi is fully compliant with the CMP API from the . 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.

getObservableOnUserConsentStatusForVendor(vendorId)

Deprecated, use instead.

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

getUserConsentStatus(purpose, vendor)

Search the purpose in getCurrentUserStatus().purposes or the vendor in getCurrentUserStatus().vendors.

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

getUserConsentStatusForPurpose(purposeId)

Search the purposeId in getCurrentUserStatus().purposes

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

getUserConsentStatusForVendor(vendor)

Search the vendorId in getCurrentUserStatus().vendors.

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

getUserStatus()

Search the purposes in getCurrentUserStatus().purposes or the vendors in getCurrentUserStatus().vendors.

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

Parameters

No parameter.

Returns

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

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.

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

openTransaction()

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

setUserStatus(parameters)

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.getCurrentUserStatus()

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
    },
  },
});

setUserStatusForAll(params)

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.getCurrentUserStatus()

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

Boolean value specifying whether all vendors' legitimate interests should be enabled or disabled

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.setUserStatusForAll({
  purposesConsentStatus: true,
  purposesLIStatus: true,
  vendorsConsentStatus: true,
  vendorsLIStatus: true,
  action: "click",
});

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

CCPA

setDoNotSellStatus(status)

Set the Do Not Sell status of the user.

Parameters

Name
Type
Description

status

boolean

true if the user has opted out of data sharing.

false if the user has not opted out of data sharing (default).

Returns

Nothing

Example

Didomi.CCPA.setDoNotSellStatus(true);

getDoNotSellStatus()

Get the Do Not Sell status of the user.

Parameters

No parameter.

Returns

Boolean

Example

Didomi.CCPA.getDoNotSellStatus();

Deprecated, use instead.

Deprecated, use instead.

Deprecated, use instead.

Deprecated, use instead.

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 (addtl_consent) and the dates of the user choices (created and updated ISO8061 dates).

Deprecated, use

You are not an EU company and you only need to collect consent for EU visitors (see 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.

Deprecated, use instead.

Deprecated, use instead.

Deprecated, use instead.

Please read on what to expect from your analytics when setting a custom behavior for your consent notice.

Deprecated, use instead.

Please read on what to expect from your analytics when setting a custom behavior for your consent notice.

Deprecated, use instead.

Google's additional consent mode
our article
our article
IAB Transparency and Consent framework version 1
Read more in the IAB documentation
Country and GDPR
addVendorStatusListener
getCurrentUserStatus
getCurrentUserStatus
getCurrentUserStatus
getCurrentUserStatus
getCurrentUserStatus().regulation
isUserStatusPartial
openCurrentUserTransaction
setCurrentUserStatus
setCurrentUserStatus
shouldUserStatusBeCollected