Preferences

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 Didomi Console and this documentation only applies to edge cases or custom implementations that require it.

Introduction

Preferences popup that opens when the user clicks on "Learn more"

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>

Disagree to all / Agree to all buttons at the top of the puproses list

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	Purpose ID to be displayed in that position. See Vendors and purposes for a list of available purposes.

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.

Read our Events section for more information:

pageEvents

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:

Information screen

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

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.