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
    • 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
  • Introduction
  • Open the popup
  • Privacy Policy
  • Text & Macros
  • Macros
  • Disable Agree/Disagree to all buttons
  • Disagree and Agree to all buttons at the top of the purposes list
  • Configuring legitimate interest legal basis status
  • Purposes
  • Order of purposes
  • Categories of purposes
  • Information screen
  • Vendors screen
  • Text
  • Display when consent is missing
  • Prevent the popup from being closed when consent is missing
  • Vendors and purposes
  1. SDKs
  2. Web SDK
  3. Configuration

Preferences

PreviousLook and feelNextTheme

Last updated 1 year ago

This section describes how to configure the Didomi consent notice through its programmatic API and the window.didomiConfig object.

Most configuration options are available through the and this documentation only applies to edge cases or custom implementations that require it.

Introduction

The "Preferences" pop-in allows the user to manage his or her preferences in terms of consent given by purpose and by vendor. By default, it is shown when the user clicks on "Learn more" in the notice (banner or popin) and we recommend adding a link on your website to open it.

Open the popup

By default, the popup can be open from the banner if the user wants to get more information.

We recommend that you also add a link to your website (in the menu or in the privacy policy) to let the user update his or her preferences.

You can do so by calling the Didomi.preferences.show() function.

Example with a link:

<a href="javascript:Didomi.preferences.show()">Manage my privacy preferences</a>

Privacy Policy

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

Example:

<script type="text/javascript">
window.didomiConfig = {
  app: {
    apiKey: '<Your API key>',
    privacyPolicyURL: 'https://privacy.didomi.io/'
  }
};
</script>

Text & Macros

You can change the content of the popup by setting properties on preferences.content.

Configuration Key

Description

preferences.content.text

Main content of the popup

preferences.content.title

Title of the popup (Welcome to ...)

preferences.content.disagreeToAll

'Disagree to all' button

preferences.content.agreeToAll

'Agree to all' button

preferences.content.save

'Save' button

preferences.content.subText

Text between the 'View all partners' button and the footer

preferences.content.viewAllPartners

'View all partners' button

preferences.content.agree

'Agree' buttons

preferences.content.disagree

'Disagree' buttons

Example:

<script type="text/javascript">
window.didomiConfig = {
  app: {
    apiKey: '<Your API key>'
  },
  preferences: {
    content: {
      text: {
        en: 'We and our partners place cookies, access and use non-sensible information from your device to improve our products and personalize ads and other contents throughout this website. [...]',
        fr: 'Nos partenaires et nous déposons des cookies et utilisons des informations non sensibles de votre appareil pour améliorer nos produits et afficher des publicités et contenus personnalisés. Vous pouvez accepter ou refuser ces différentes opérations. [...]'
      },
      title: {
        en: 'Welcome to our website',
        fr: 'Bienvenue sur notre site'
      },
      disagreeToAll: {
        en: 'Disagree to all',
        fr: 'Refuser tout'
      },
      agreeToAll: {
        en: 'Agree to all',
        fr: 'Accepter tout'
      },
      save: {
        en: 'Save',
        fr: 'Sauvegarder'
      },
      viewAllPartners: {
        en: 'View all partners',
        fr: 'Voir nos partenaires'
      },
      agree: {
        en: 'Agree',
        fr: 'Accepter'
      },
      disagree: {
        en: 'Disagree',
        fr: 'Refuser'
      }
    }
  }
};
</script>

Note that you should provide translations for all the languages that your website supports. We provide translations for all our standard messages.

Macros

You can use macros that will get replaced with the actual value configured when the text gets rendered.

Macro

Value

Description

{privacyPolicyURL}

app.privacyPolicyURL

Privacy Policy URL

{websiteName}

app.name

Name of your website

{numberOfPartners}

A dynamic value that displays a numeric count of all vendors

{numberOfIABPartners}

A dynamic value that displays a numeric count of IAB vendors

{numberOfNonIABPartners}

A dynamic value that displays a numeric count of all vendors excluding IAB vendors

Disable Agree/Disagree to all buttons

By default, we display "Agree to all" and "Disagree to all" buttons at the bottom of the list of purposes to allow the user to agree or disagree in a single click:

You can disable these buttons and only display the Save button to force the user to make individual choices by purpose by switching enableAllButtons to false . In that case, the user will have to manually agree/disagree to each purposes:

Example:

<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    enableAllButtons: true,
  }
};
</script>

Disagree and Agree to all buttons at the top of the purposes list

We can enable "Agree to all" and "Disagree to all" buttons at the top of the list of purposes by setting enableBulkActionOnPurposes to true in the notice object.

Example:

<script type="text/javascript">
window.didomiConfig = {
  notice: {
    enableBulkActionOnPurposes: true,
  }
};
</script>

When "Disagree to all" and "Agree to all" buttons are visible all other purposes buttons will be adjusted in width to be aligned with bulk action buttons. There are number of changes in the styling for bulk action buttons and purposes buttons that the WEB SDK applies in this case:

Bulk buttons

font-size

12px !important

box-sizing

border-box

Purposes buttons

box-sizing

border-box

A custom CSS that changes the didomi-components-radio__option class could break buttons alignment and places buttons outside of the notice

Configuring legitimate interest legal basis status

After clicking on the Disagree to all button in the purposes screen, all purposes' and vendors' consents and legitimate interests are disabled by default.

To keep legitimate interests enabled after clicking on the Disagree to all button, preferences.denyAppliesToLI should be set to false in the Didomi configuration object:

<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    denyAppliesToLI: false
  }
};
</script>

Purposes

Order of purposes

You can control the order in which purposes should be displayed.

This can be done by adding an array of purposes in the preferences.categories property in the didomiConfig object. The order in which items are added to this array will be the same order in which purposes will be displayed in based on their purposeId.

Purposes that are required by some vendors and that are not included in the list will be appended to the end of the list in alphabetical order to make sure that all required purposes are displayed and that consent is correctly collected.

didomi_config.json
<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    categories: [
      {
        type: 'purpose',
        purposeId: 'cookies'
      },
      {
        type: 'purpose',
        purposeId: 'advertising_personalization'
      },
      {
        type: 'purpose',
        purposeId: 'ad_delivery'
      }
    ]
  }
};
</script>

Configuration Key

Type

Description

preferences.categories[index].type

String

Type of the entity to be displayed. If you are specifying a purpose, this key should have purpose value.

preferences.categories[index].purposeId

String

Categories of purposes

Purposes having a similar functionality can be optionally grouped into categories. This could be useful for better clarity of the purposes screen.

To group purposes into categories, the preferences.categories configuration option in the Didomi configuration can be used:

<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    categories: [
      {
        id: 'category-id',
        type: 'category',
        name: {
          en: 'Category name'
        },
        description: {
          en: 'Category description'
        },
        children: [
          {
            type: 'purpose',
            purposeId: 'cookies'
          }
        ]
      }
    ]
  }
};
</script>

Purposes that are required by some vendors and that are not included in one of the specified categories will be appended to the end of the purposes list in alphabetical order so that all required purposes are displayed and that consent is correctly collected for them.

Each category has the following configuration keys:

Configuration Key

Type

Description

category.id

String

Unique category identifier

category.name

Object

An object containing language ISO code as keys and the localized category name as values

category.description

Object

An object containing language ISO code as keys and the localized category description as values

category.children

Array

An array of purposes and/or categories which are included in the specified category

category.type

String

Type of the entity to be displayed. If you are specifying the category, this key should have category value

If the user has agreed to the whole category, thepreferences.clickcategoryagree Didomi event will be dispatched. Similarly, if the user has disagreed with the whole category, the preferences.clickcategorydisagree Didomi event will be dispatched.

Information screen

You can embed an intermediate information screen that shows when the user clicks on "Learn More" in the consent notice. That information screen will be displayed before the Preferences screen where the user can give consent per purpose. Example:

To enable the information screen with a custom message as well as a custom text for the buttons per language :

<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    information: {
      enable: true,

      content: {
        text: {
          en: 'Information in English',
          fr: 'Information en français'
        },
        learnMore: {
          en: 'Learn More',
          fr: 'En savoir plus'
        },
        agreeAndClose: {
          en: 'Agree and Close',
          fr: 'Accepter et Fermer'
        }
      }
    }
  }
};
</script>

There is no default text for the information screen so you must specify one or the screen will be empty.

Vendors screen

By clicking on the View our partners button, you will access this screen where you can block certain vendors.

Text

You can change the content of the popup by setting properties on preferences.content.

Configuration Key

Description

preferences.content.textVendors

Main content of the popup

preferences.content.subTextVendors

Text between the list of vendors and the footer

preferences.content.authorizeVendors

Authorize buttons

preferences.content.blockVendors

Block buttons

Display when consent is missing

If you want to bypass the notice and display the Preferences popup directly when consent is missing, you can set the property preferences.showWhenConsentIsMissing to true. When that is configured, you also need to disable the regular notice to ensure that it will not be displayed by setting notice.enable to false.

<script type="text/javascript">
window.didomiConfig = {
  notice: {
    enable: false
  },
  preferences: {
    showWhenConsentIsMissing: true
  }
};
</script>

Prevent the popup from being closed when consent is missing

By default, the Preferences popup can be closed at any time, even if the user has not made a choice for some purposes. You can choose to hide the "X" icon and disallow closing the popup until the user has expressed a choice for every purpose by setting canCloseWhenConsentIsMissing to false.

<script type="text/javascript">
window.didomiConfig = {
  preferences: {
    canCloseWhenConsentIsMissing: true
  }
};
</script>

Vendors and purposes

You must configure the vendors for which consent is collected by our consent notice and displayed in the preferences popup.

Read our detailed section to see how they can be configured.

Purpose ID to be displayed in that position. See for a list of available purposes.

Read our section for more information:

Events
Events
Vendors and purposes
Didomi Console
Preferences popup that opens when the user clicks on "Learn more"
Disagree to all / Agree to all buttons at the top of the puproses list
Information screen
Vendors screen