Vendors and purposes

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

Our consent notice is collecting consent for a given set of vendors and purposes as it is a requirement under the GDPR.

You must configure the list of vendors that are embedded on your website and the associated purposes will be automatically determined. Additionally, you must make sure that the consent status is shared with the vendor and that it is correctly enforced.

We support vendors from the IAB global vendors list and from our own list of vendors. You can also add custom vendors as needed if they are not supported by either list.

Vendors

As per the regulation, the consent notice collects consents for a specific set of vendors and purposes. You must configure the notice to let it know what vendors are used on your website and it will automatically determine what purposes are required.

If you are installing Didomi through one of our partners, the consent notice might already be pre-configured with some vendors. You can add more to the list to make sure that all your vendors are included but you want to make sure to also add back those pre-configured vendors.

That list of purposes and vendors is the one used in the popup as well.

We currently support three types of vendors:

  • Didomi vendors: We manage this list ourselves and map the purposes.

  • IAB vendors: A list of vendors managed by the IAB in the IAB global vendors list.

  • Custom vendors: Any vendor that you are configuring yourself.

The consent information collected for these vendors is automatically shared with them when possible. Vendors that we do not have an integration with can be managed through your tag manager.

Didomi vendors

For Didomi vendors, you can configure the list of vendors embedded on your website in the app.vendors.didomi configuration object:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
didomi: [
'google'
]
}
}
};
</script>

Here is our current list of vendors in that list:

ID

Name

Products

Direct integration?

google

Google

Google DFP, AdSense and Adx

Yes (see the detailed guide)

amazon

Amazon

Amazon A9

Not needed

facebook

Facebook

Facebook widgets (Like/Share buttons)

No

twitter

Twitter

Twitter widgets

No

If we do not have a direct integration with one of those vendors, you must ensure that their tags/widgets only get loaded after the user has given consent to be compliant with the GDPR. Please read the dedicated tags management section to understand how to do that.

IAB vendors

You can configure the list of IAB vendors that you want to collect consent for.

IAB vendors will automatically pull the consent status of the user from the Didomi SDK. You do not need to manage them through your tag manager but you want to make sure that you are using JavaScript tags. Image pixels will not be able to pull consent information from Didomi.

You can choose the IAB TCF version you are using on your website in the app.vendors.iab configuration object.

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
version: 2, // IAB TCF Version (1 or 2)
}
}
}
};
</script>

Support for TCF version 1 will end on 8/15/2020 so we recommend using version 2 from now on.

Include all vendors from the IAB list

The parameter iab can also be set to an object to include the entire list of IAB vendors from the global vendors list:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
all: true, // Include the entire list of IAB vendors (defaults to 'false')
exclude: [3] // Exclude some vendors if you set all to 'true'
}
}
}
};
</script>

When this option is enabled, consent will be collected every time new vendors are added to the list. Didomi updates the list from the IAB global vendor list once every month which means that your visitors will see the consent notice every month. Previously collected consents will not be re-collected.

Custom list of IAB vendors

You can set a custom list of vendors embedded on your website in the app.vendors.iab configuration object:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
include: [
9,
27,
25,
28,
30
]
}
}
}
};
</script>

The list of IDs passed must be vendors coming from the IAB global vendors list.

If you use Prebid, you must enable the Prebid consentManagement module as well. Please read our dedicated section.

Custom vendors

You can configure your own custom vendors and map them to purposes by specifying a unique ID, their name and privacy policy URL:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
custom: [
{
// Unique ID for the vendor
id: 'custom-vendor',
// Display name of the vendor
name: 'Custom Vendor',
// List of purposes that you want to collect consent for, for this vendor
purposeIds: [
'cookies',
'advertising_personalization',
'content_personalization',
'ad_delivery',
'analytics'
],
// URL to the privacy policy of the vendor
policyUrl: 'http://www.vendor.com/privacy-policy'
}
]
}
}
};
</script>

You must specify all the fields (id, name ,purposeIds and policyUrl ) for custom vendors. If one of them is not present, the vendor will be ignored and consent will not be collected.

You ID will also be prefixed with c: once registered so that any request to the Didomi SDK API or through your tag manager must specify that namespace. For instance, if you wanted to know if you had consent for the purpose cookies and the vendor custom-vendor, you would do: Didomi.getUserConsentStatus('cookies', 'c:custom-vendor').

Delay the loading of your custom vendors' tags

If you embed a tag or widget from a custom vendor, you must ensure that it only get loaded after the user has given consent to be compliant with the GDPR. Please read the dedicated tags management section to do that.

ID format

The ID assigned to your custom purpose must be a lowercase string with only alphabetical characters, numbers, - or _ ([a-z0-9-_)]).

Purposes

As mentioned before, if you are using standard vendors from the IAB or Didomi lists, you do not need to specify purposes. You can specify purposes for custom vendors or custom purposes as needed.

Standard purposes

We currently support the following list of purposes:

Name

Description

ID

Information storage and access (Cookies)

The storage of information, or access to information that is already stored, on your device such as advertising identifiers, device identifiers, cookies, and similar technologies.

cookies

Personalisation

The collection and processing of information about your use of this service to subsequently personalise advertising and/or content for you in other contexts, such as on other websites or apps, over time. Typically, the content of the site or app is used to make inferences about your interests, which inform future selection of advertising and/or content.

advertising_personalization

Ad selection, delivery, reporting

The collection of information, and combination with previously collected information, to select and deliver advertisements for you, and to measure the delivery and effectiveness of such advertisements. This includes using previously collected information about your interests to select ads, processing data about what advertisements were shown, how often they were shown, when and where they were shown, and whether you took any action related to the advertisement, including for example clicking an ad or making a purchase. This does not include personalisation, which is the collection and processing of information about your use of this service to subsequently personalise advertising and/or content for you in other contexts, such as websites or apps, over time.

ad_delivery

Content selection, delivery, reporting

The collection of information, and combination with previously collected information, to select and deliver content for you, and to measure the delivery and effectiveness of such content. This includes using previously collected information about your interests to select content, processing data about what content was shown, how often or how long it was shown, when and where it was shown, and whether the you took any action related to the content, including for example clicking on content. This does not include personalisation, which is the collection and processing of information about your use of this service to subsequently personalise content and/or advertising for you in other contexts, such as websites or apps, over time.

content_personalization

Analytics & Measurement

The collection of information about your use of the content, and combination with previously collected information, used to measure, understand, and report on your usage of the service. This does not include personalisation, the collection of information about your use of this service to subsequently personalise content and/or advertising for you in other contexts, i.e. on other service, such as websites or apps, over time.

analytics

These purposes are automatically mapped to IAB purposes for all vendors in the IAB vendor list or in the Didomi list.

Custom purposes

You can add additional purposes if needed with the app.customPurposes property. This is useful for storing consent to custom purposes that are specific to your company.

Example:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
customPurposes: [
{
id: 'my_custom_purpose',
name: {
en: 'My custom purpose',
fr: 'Ma propre finalité'
},
description: {
en: 'A more complete description of why you are collecting data and how you are processing it',
fr: 'Une description plus complète de la raison pour laquelle vous collectez des données et comment vous les traitez'
}
}
]
}
};
</script>

ID format

The ID assigned to your custom purpose must be a lowercase string with only alphabetical characters, numbers, - or _ ([a-z0-9-_)]). The SDK will throw an error in your browser console if that is not the case.

Custom purposes are treated the same way as standard purposes and can be mapped to custom vendors as needed. Didomi will store the consents from the user to these purposes and make them available through our API just like any other purpose.

Essential purposes

Under the ePrivacy directive, some purposes can be deemed as essential which means that they cannot be disabled by users as they are technically essential to the website.

You can add essential purposes when needed with the app.essentialPurposes property. This allows you to define purposes that are essential for your website.

Example:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
customPurposes: [
{
id: 'my_custom_purpose',
name: {
en: 'My custom purpose',
fr: 'Ma propre finalité',
},
description: {
en:
'A more complete description of why you are collecting data and how you are processing it',
fr:
'Une description plus complète de la raison pour laquelle vous collectez des données et comment vous les traitez',
},
},
],
essentialPurposes: ['my_custom_purpose'],
},
};
</script>

Essential purposes values

Essential purposes must be custom purposes. If the purpose is specified as essential but it is not a custom purpose, it will be ignored from the essential purposes values. IAB purposes cannot be marked as essential.

Didomi does not store consent statuses for essential purposes as there is no consent collected for them. Since they are required by the website, they always have accepted consent status, which cannot be changed by the user.

Essential purposes always behave like purposes with accepted consent status, including the case when calling Web SDK API methods, like getUserConsentStatusForPurpose.

Example:

// Always returns true
Didomi.getUserConsentStatusForPurpose('essential_purpose');

Read our Reference section for more information:

Publisher restrictions (IAB TCF)

The IAB TCF version 2 allows publishers to set restrictions on purposes and legal basis used by vendors.

If you want to specify publisher restrictions, you have to set the IAB TCF version to be 2.

Publisher restrictions are defined by the following properties:

ID

This value represents a unique identifier for the specified publisher restriction.

Purpose ID

The purpose that the restriction applies to. This value has to be an IAB purpose ID.

Vendors

The vendors that the restriction applies to. A restriction can apply to all TCF vendors or to a specific list of vendor IDs.

If a restriction applies to all vendors, the configuration should contain all for the key vendors.typein the publisher restrictions configuration:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
version: 2,
all: true,
restrictions: [
{
id: 'demo-restriction',
purposeId: 'cookies',
vendors: {
type: 'all'
},
restrictionType: 'disallow'
}
]
}
}
}
};
</script>

If a restriction applies to a specific set of vendor IDs, the configuration should contain list for the key vendors.typein the publisher restrictions configuration.

The list of vendors that the restriction applies to can be specified in two formats:

  • Ranges in the key vendors.ranges in the restrictions configuration that should be specified as an array of ranges to which a specified restriction applies:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
version: 2,
all: true,
restrictions: [
{
id: 'demo-restriction',
purposeId: 'cookies',
vendors: {
type: 'list',
ranges: [{ start: 1, end: 10 }]
},
restrictionType: 'disallow'
}
]
}
}
}
};
</script>
  • List of vendor IDs in the key vendors.ids in the restrictions configuration:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
version: 2,
all: true,
restrictions: [
{
id: 'demo-restriction',
purposeId: 'cookies',
vendors: {
type: 'list',
ids: [1, 2, 3, 4, 5]
},
restrictionType: 'disallow'
}
]
}
}
}
};
</script>

Restriction type

There are 4 available restriction types:

Restriction

Description

Key

Allow purpose

Allow vendors to process data for the specified purpose

allow

Disallow purpose

Do not allow vendors to process data for the specified purpose

disallow

Require consent

Only allow purpose to be processed with consent as a legal basis

req-consent

Require legitimate interest

Only allow purpose to be processed with legitimate interest as a legal basis

req-li

Stacks (IAB TCF)

The IAB TCF version 2 allows setting IAB TCF stacks to show in the consent notice.

If you want to specify IAB TCF stacks, you have to set the IAB TCF version to be 2.

Stacks represent combinations of purposes and special features that are used for data processing. They may be used to substitute more granular purposes and special features names in the data processing list within the consent notice.

Read our Notice section for more information on the consent notice configuration, customization, and data processing:

Configuration

By default, we automatically determine the best stacks to use to cover all required purposes and special features.

If you would like to override this behavior and specify the exact list of stacks to use, you can do so by specifying the stacks.ids property:

<script type="text/javascript">
window.didomiConfig = {
app: {
apiKey: '<Your API key>',
vendors: {
iab: {
version: 2,
all: true,
stacks: {
ids: [1, 2]
}
}
}
},
notice: {
showDataProcessing: true
}
};
</script>