# Preferences

{% hint style="danger" %}
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](https://console.didomi.io/) and this documentation only applies to edge cases or custom implementations that require it.
{% endhint %}

## Introduction

![Preferences popup that opens when the user clicks on "Learn more"](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-eed4879ffff0ce93885b552653a83922056b8c76%2FPreferences.png?alt=media)

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:

```markup
<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:

```javascript
<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:

```javascript
<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:

![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-302b4d88b2ec2447603aa68d45f7d0ff035765e0%2FCapture%20d%E2%80%99%C3%A9cran%2C%20le%202019-03-01%20%C3%A0%2019.07.22.png?alt=media)

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:

![](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-de4f141a80bf169aed81a481fbc53a5ecf12dea7%2FCapture%20d%E2%80%99%C3%A9cran%2C%20le%202019-03-01%20%C3%A0%2019.06.58.png?alt=media)

Example:

```javascript
<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:

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

![Disagree to all / Agree to all buttons at the top of the puproses list](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-1a23e24874a1ffc56c883bc15bff4819ca2c9f99%2FScreenshot%202022-07-21%20at%2017.38.13.png?alt=media)

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

{% hint style="danger" %}
A custom CSS that changes the `didomi-components-radio__option` class could break buttons alignment and places buttons outside of the notice
{% endhint %}

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

```javascript
<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.

{% code title="didomi\_config.json" %}

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

{% endcode %}

| 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](https://gitlab.com/didomi/developers-documentation/-/blob/main/docs/cmp/web-sdk/consent-notice/broken-reference/README.md) 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:

```javascript
<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, the`preferences.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](https://developers.didomi.io/cmp/web-sdk/reference/events) section for more information:

{% content-ref url="../reference/events" %}
[events](https://developers.didomi.io/cmp/web-sdk/reference/events)
{% endcontent-ref %}

## 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](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-7836818606421378d3035bb3276a8efdfdb6b214%2Fconsent-popup-information.png?alt=media)

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

```javascript
<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](https://1703900661-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LDh8ZWDZrXs8sc4QKEQ%2Fuploads%2Fgit-blob-7eb165503dbc265d513e44f8c47900a9491215e3%2FVendors%20screen.png?alt=media)

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.

{% code title="" %}

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

{% endcode %}

## 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`.

{% code title="" %}

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

{% endcode %}

## 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](https://gitlab.com/didomi/developers-documentation/-/blob/main/docs/cmp/web-sdk/consent-notice/broken-reference/README.md) to see how they can be configured.