Vendors and purposes

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 in your app 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 in your app and it will automatically determine what purposes are required. That list of purposes and vendors is the one used in the preferences 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.

Didomi vendors

Important
You must manually pass the consent information to these vendors or block their SDKs as needed. Read our Third-party SDKs section to learn how.
For Didomi vendors, you can configure the list of vendors embedded in your in the app.vendors.didomi configuration object of your didomi_config.json file:
{
"app": {
"vendors": {
"didomi": [
"google"
]
}
}
}
Here is our current list of vendors in that list:
ID
Name
Products
google
Google
Google DFP, AdSense and Adx
amazon
Amazon
Amazon A9
facebook
Facebook
Facebook widgets (Like/Share buttons)
twitter
Twitter
Twitter widgets

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 manually pass consent information to them. Do make sure that you have the latest versions of your third-party SDKs as the IAB specification support is usually very recent.
By default, the SDK is configured to collect consent for all IAB vendors.
You can choose the IAB TCF version you are using on your app in the app.vendors.iab configuration object.
{
"app": {
"vendors": {
"iab": {
"version": 2, // IAB TCF Version (1 or 2)
}
}
}
}
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 (default)

The parameter iab can be set to an object to include the entire list of IAB vendors from the global vendors list:
{
"app": {
"vendors": {
"iab": {
"all": true,
"exclude": [3]
}
}
}
}
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.
The app.vendors.iab.exclude parameter is optional and allows you to exclude some IAB vendor IDs from the list.

Custom list of IAB vendors

You can set a custom list of vendors embedded in your app in the app.vendors.iab configuration object:
{
"app": {
"vendors": {
"iab": {
"include": [1, 2, 3, 4, 5]
}
}
}
}
The list of IDs passed must be vendors coming from the IAB global vendors list.

Custom vendors

Important
You must manually pass the consent information to these vendors or block their SDKs as needed. Read our Third-party SDKs section to learn how.
You can configure your own custom vendors and map them to purposes by specifying a unique ID, their name and privacy policy URL:
{
"app": {
"vendors": {
"custom": [
{
"id": "custom-vendor",
"name": "Custom Vendor",
"purposeIds": [
"cookies"
],
"policyUrl": "https://www.test.com"
}
]
}
}
}
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. The list of available purpose IDs is below.
Your ID will also be prefixed with c: once registered so that any request to the Didomi SDK API must specify that prefix. For instance, if you wanted to know if you had consent for the vendor custom-vendor, you would do: Didomi.getInstance().getUserStatus().vendors.consent.enabled.contains("c:custom-vendor")
We support additional/optional fields to include cookies maximum duration (if the vendor creates cookies) and non-cookies (device storage) information for custom vendors. These fields are:
Field
Type
Description
cookieMaxAgeSeconds
integer
The number of seconds representing the longest potential duration for cookies stored on a device by the vendor.
usesNonCookieAccess`
boolean
Indicates whether the vendor uses other, non-cookie methods of storage or accessing information already stored on a user’s device (see footnote 1). Examples of non-cookie storage and access may be localStorage, indexDB, mobile ad IDs, etc.
deviceStorageDisclosureUrl
string
Link to a recommended, vendor-hosted, secure URL for disclosing additional storage information (see “deviceStorage.json” for additional details).
Although dealing with non-IAB vendors in this section, we are following the IAB guidelines for Device Storage Duration and Access Disclosure to define and configure them.
You can configure the device storage duration and disclosures for custom vendors by specifying these fields:
{
"app": {
"vendors": {
"custom": [
{
"id": "custom-vendor",
"name": "Custom Vendor",
"purposeIds": [
"cookies"
],
"policyUrl": "https://www.test.com"
// Longest potential duration for cookie storage
"cookieMaxAgeSeconds": 2592000,
// Vendor uses non-cookie storages
"usesNonCookieAccess": true,
// URL with additional storage information
"deviceStorageDisclosureUrl": "https://www.test.com/deviceStorage.json"
}
]
}
}
}

Map custom vendor to IAB vendor

You can map a custom vendor to an IAB vendor if you need to override the default configuration of the IAB vendor (for adding new purposes to it, for instance). To do so, simply add an iabId property to the custom vendor definition with the ID of the IAB vendor that you want to override:
{
"app": {
"vendors": {
"custom": [
{
"id": "custom-vendor",
"name": "Custom Vendor",
"purposeIds": [
"cookies"
],
"policyUrl": "https://www.test.com",
"iabId": "1"
}
]
}
}
}

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.

Standard purposes

We currently support the following list of IAB TCF v2 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
Select basic ads
Ads can be shown to you based on the content you’re viewing, the app you’re using, your approximate location, or your device type.
select_basic_ads
Create a personalised ads profile
A profile can be built about you and your interests to show you personalised ads that are relevant to you.
create_ads_profile
Select personalised ads
Personalised ads can be shown to you based on a profile about you.
select_personalized_ads
Create a personalised content profile
A profile can be built about you and your interests to show you personalised content that is relevant to you.
create_content_profile
Select personalised content
Personalised content can be shown to you based on a profile about you.
select_personalized_content
Measure ad performance
The performance and effectiveness of ads that you see or interact with can be measured.
measure_ad_performance
Measure content performance
The performance and effectiveness of content that you see or interact with can be measured.
measure_content_performance
Apply market research to generate audience insights
Market research can be used to learn more about the audiences who visit sites/apps and view ads.
market_research
Develop and improve products
Your data can be used to improve existing systems and software, and to develop new products
improve_products
We also support the following list of special features:
Name
Description
ID
Use precise geolocation data
Your precise geolocation data can be used in support of one or more purposes. This means your location can be accurate to within several meters.
geolocation_data
Actively scan device characteristics for identification
Your device can be identified based on a scan of your device's unique combination of characteristics.
device_characteristics
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 or to some of your vendors.
Example:
didomi_config.json
{
"app": {
"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"
}
}
]
}
}
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 app.
You can add essential purposes when needed with the app.essentialPurposes property. This allows you to define purposes that are essential for your app.
Example:
{
"app": {
"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'],
},
}
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 app, 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.

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:
{
"app": {
"vendors": {
"iab": {
"version": 2,
"all": true,
"restrictions": [
{
"id": 'demo-restriction',
"purposeId": 'cookies',
"vendors": {
"type": 'all'
},
"restrictionType": 'disallow'
}
]
}
}
}
}
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 is specified by the key vendor.ids in the restriction configuration :
{
"app": {
"vendors": {
"iab": {
"version": 2,
"all": true,
"restrictions": [
{
"id": 'demo-restriction',
"purposeId": 'cookies',
"vendors": {
"type": 'list',
"ids": [1, 2, 3, 4, 5]
},
"restrictionType": 'disallow'
}
]
}
}
}
}
Specifying vendors list by an array of ranges is not supported at the moment

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