Create and publish a multi-regulation consent notice
This tutorial will walk you through the steps necessary to create a multi-regulation notice, modify its configuration, and publish it.
Please be aware that requests for multi-regulation notices specify the v:"2"
header value; don't forget to include this in your API requests to the /widgets/notices
and /widgets/notices/configs
endpoints.
Create a consent notice
To create a consent notice, send a POST /widgets/notices
request with the name of the notice to create and the ID of the organization that the notice belongs to:
const bent = require("bent");
const organizationId = "didomi";
const headers = {
Authorization: `Bearer ${token}`,
v: "2",
};
const client = {
post: bent(
"POST",
"https://api.didomi.io/v1",
"json",
headers,
201
),
};
(async () => {
console.log(`Creating a notice for organization ${organizationId} ...`);
const notice = await client.post("/widgets/notices", {
organization_id: organizationId,
name: "My consent notice",
});
console.log(`Notice with ID ${notice.id} created!`);
})();
curl --request POST 'https://api.didomi.io/v1/widgets/notices' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'v: 2' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "My consent notice",
"organization_id": "didomi"
}'
The API will return a response similar to:
{
"name": "My consent notice",
"archived_at": null,
"organization_id": "didomi",
"id": "7wmRYUH6",
"created_at": "2021-03-27T08:38:10.831Z",
"updated_at": "2021-03-27T08:38:10.831Z",
"version": 0
}
Modify the notice's draft multi-regulation configuration
The API automatically created a draft configuration when a notice was created. To update the notice configuration, you must first get the ID of the draft configuration and then modify that draft configuration.
Get the ID of the draft configuration
To get the ID of the draft configuration, get the list of all configurations:
const bent = require("bent");
const noticeId = "QdA3yxfi";
const BASE_URL = "https://api.didomi.io/v1";
const headers = {
Authorization: `Bearer ${token}`,
v: "2",
};
const client = {
get: bent("GET", BASE_URL, "json", headers),
patch: bent("PATCH", BASE_URL, "json", headers),
post: bent("POST", BASE_URL, "json", headers, 201),
};
(async () => {
console.log("Getting the latest draft config ...");
// Get the Configuration related to our notice with deployed_at as NULL.
const {
data: [draftConfiguration],
} = await client.get(
`/widgets/notices/configs?notice_id=${noticeId}&deployed_at=null`
);
console.log(
`A default notice has ${draftConfiguration.regulation_configurations.length} Regulation-Configurations`
);
// prints: A default notice has 3 Regulation-Configurations
console.log(
`A default notice has ${
draftConfiguration.regulation_configurations.filter(
(rc) => rc.regulation_id === "gdpr"
).length
} GDPR related Regulation-Configurations`
);
// prints: A default notice has 3 GDPR related Regulation-Configurations
const defaultGdprConfigurations =
draftConfiguration.regulation_configurations.filter(
(rc) => rc.regulation_id === "gdpr" && rc.is_default_regulation_config
);
console.log(
`A regulation should only have 1 default configuration hence our Configuration is ${
defaultGdprConfigurations.length === 1 ? "valid" : "invalid"
}!`
);
// prints: A regulation should only have 1 default Regulation-Configuration hence our Configuration is valid!
const italyOverride = draftConfiguration.regulation_configurations.find(
(rc) =>
rc.regulation_id === "gdpr" &&
!rc.is_default_regulation_config &&
rc.geo_locations.length === 1 &&
rc.geo_locations[0] === "IT"
);
const franceOverride = draftConfiguration.regulation_configurations.find(
(rc) =>
rc.regulation_id === "gdpr" &&
!rc.is_default_regulation_config &&
rc.geo_locations.length === 1 &&
rc.geo_locations[0] === "FR"
);
if (italyOverride && franceOverride) {
console.log(
"A default notice has overrides set up for France and Italy to comply with local requirements."
);
} else {
throw new Error("Something went wrong :(");
}
})();
curl -X GET \
'https://api.didomi.io/v1/widgets/notices/configs?notice_id=<NOTICE_ID>&deployed_at=null' \
-H 'Authorization: Bearer <AUTH_TOKEN>' \
-H 'v: 2'
{
"total": 1,
"limit": 100,
"skip": 0,
"data": [
{
"custom_json": {},
"config": {
"user": {
"bots": {
"consentRequired": false
}
},
"notice": {
"position": "bottom",
"showDataProcessing": true
},
"languages": {
"default": "en",
"enabled": [
"en",
"fr"
]
}
},
"default": false,
"platform": "web",
"targets": [],
"text_mode": "approved",
"text_id": "LZJ3VTcz",
"full_atp": true,
"enable_ignore_consent_before": false,
"ignore_consent_before": null,
"negative_action": "button",
"negative_action_link": false,
"negative_action_link_format": "cross",
"negative_action_button": false,
"disagree_button_style": "primary",
"country": null,
"notice_deny_applies_to_li": true,
"preferences_deny_applies_to_li": true,
"consent_duration": 12,
"consent_duration_unit": "months",
"denied_consent_duration": 12,
"denied_consent_duration_unit": "months",
"denied_consent_duration_custom": false,
"cross_device_enabled": false,
"cross_device_timeout": 3000,
"gcm_enabled": false,
"gcm_set_default_status": true,
"gcm_data_layer_name": null,
"gcm_analytics_default_status": false,
"gcm_ads_default_status": false,
"gcm_functionality_default_status": true,
"gcm_personalization_default_status": true,
"gcm_security_default_status": true,
"template_id": null,
"regulation_configurations": [
{
"id": "HfEYXa4L",
"regulation_id": "gdpr",
"is_default_regulation_config": true,
"geo_locations": [
"AD",
"AT",
"BE",
"BG",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GF",
"GG",
"GI",
"GP",
"GR",
"HR",
"HU",
"IE",
"IS",
"IT",
"JE",
"LI",
"LT",
"LU",
"LV",
"MC",
"MF",
"MQ",
"MT",
"NL",
"NO",
"PL",
"PT",
"RE",
"RO",
"SE",
"SI",
"SK",
"SM",
"VA",
"YT"
],
"regulation_settings": {},
"config": {
"app": {
"vendors": {
"iab": {
"all": false,
"stacks": {
"auto": true
},
"enabled": true,
"version": 2
},
"include": [
"googleana-4TXnJigR",
"google"
]
}
},
"preferences": {
"categories": [
{
"type": "purpose",
"purposeId": "cookies"
},
{
"type": "purpose",
"purposeId": "measure_content_performance"
},
{
"type": "purpose",
"purposeId": "create_ads_profile"
},
{
"type": "purpose",
"purposeId": "create_content_profile"
},
{
"type": "purpose",
"purposeId": "improve_products"
},
{
"type": "purpose",
"purposeId": "market_research"
},
{
"type": "purpose",
"purposeId": "measure_ad_performance"
},
{
"type": "purpose",
"purposeId": "select_basic_ads"
},
{
"type": "purpose",
"purposeId": "select_personalized_ads"
},
{
"type": "purpose",
"purposeId": "select_personalized_content"
}
]
}
},
"disabled_at": null,
"created_at": "2023-03-23T08:47:32.558Z",
"updated_at": "2023-03-23T08:47:32.558Z",
"enable_ignore_consent_before": null,
"disagree_button_style": null,
"consent_duration": null,
"consent_duration_unit": null,
"denied_consent_duration": null,
"denied_consent_duration_unit": null,
"denied_consent_duration_custom": null,
"gcm_enabled": true,
"gcm_set_default_status": null,
"gcm_analytics_default_status": null,
"gcm_ads_default_status": null,
"gcm_functionality_default_status": null,
"gcm_personalization_default_status": null,
"gcm_security_default_status": null,
"negative_action_link_format": null,
"notice_deny_applies_to_li": null,
"preferences_deny_applies_to_li": null,
"version": 0,
"negative_action_link": null,
"negative_action_button": null,
"gcm_data_layer_name": null,
"full_atp": null,
"notice_config_id": "g4xH3ypQ",
"organization_id": "didomi"
},
{
"id": "m33TZCqY",
"regulation_id": "gdpr",
"is_default_regulation_config": false,
"geo_locations": [
"IT"
],
"regulation_settings": {},
"config": {},
"disabled_at": null,
"created_at": "2023-03-23T08:47:32.558Z",
"updated_at": "2023-03-23T08:47:32.558Z",
"enable_ignore_consent_before": null,
"disagree_button_style": null,
"consent_duration": null,
"consent_duration_unit": null,
"denied_consent_duration": null,
"denied_consent_duration_unit": null,
"denied_consent_duration_custom": null,
"gcm_enabled": null,
"gcm_set_default_status": null,
"gcm_analytics_default_status": null,
"gcm_ads_default_status": null,
"gcm_functionality_default_status": null,
"gcm_personalization_default_status": null,
"gcm_security_default_status": null,
"negative_action_link_format": "cross",
"notice_deny_applies_to_li": null,
"preferences_deny_applies_to_li": null,
"version": 0,
"negative_action_link": true,
"negative_action_button": false,
"gcm_data_layer_name": null,
"full_atp": null,
"notice_config_id": "g4xH3ypQ",
"organization_id": "didomi"
},
{
"id": "G72tRBmY",
"regulation_id": "gdpr",
"is_default_regulation_config": false,
"geo_locations": [
"FR"
],
"regulation_settings": {},
"config": {},
"disabled_at": null,
"created_at": "2023-03-23T08:47:32.558Z",
"updated_at": "2023-03-23T08:47:32.558Z",
"enable_ignore_consent_before": null,
"disagree_button_style": null,
"consent_duration": null,
"consent_duration_unit": null,
"denied_consent_duration": null,
"denied_consent_duration_unit": null,
"denied_consent_duration_custom": null,
"gcm_enabled": null,
"gcm_set_default_status": null,
"gcm_analytics_default_status": null,
"gcm_ads_default_status": null,
"gcm_functionality_default_status": null,
"gcm_personalization_default_status": null,
"gcm_security_default_status": null,
"negative_action_link_format": "text",
"notice_deny_applies_to_li": null,
"preferences_deny_applies_to_li": null,
"version": 0,
"negative_action_link": false,
"negative_action_button": true,
"gcm_data_layer_name": null,
"full_atp": null,
"notice_config_id": "g4xH3ypQ",
"organization_id": "didomi"
}
],
"secure_cookies": false,
"notice_id": "FDPhA7fP",
"organization_id": "didomi",
"deployed_by": null,
"deployed_by_type": null,
"deployed_by_name": null,
"deployed_at": null,
"id": "g4xH3ypQ",
"created_at": "2023-03-23T08:47:32.529Z",
"updated_at": "2023-03-23T08:47:32.529Z",
"version": 0,
"deployed_metadata": {}
}
]
}
The configuration is called "draft" because its deployed_at
field is null
which indicates that this configuration has not been published before and can be modified.
As we are working with a newly created notice in this tutorial, we can assume that it has a single associated configuration and that it is a draft. If you are working with an existing notice that might have been published before and would have multiple configurations, read our documentation to find the current draft documentation.
Modify the draft configuration
To modify the draft configuration, send a PATCH
request with the updated configuration. In this example, we change the cross-regulation defaults for consent duration to 12 months and include CPRA as a targeted regulation for California, United States.
const bent = require("bent");
const organizationId = "<organizationId>";
const noticeId = "<noticeId>";
const BASE_URL = "https://api.didomi.io/v1";
const token = "<token>>"; // Get a token by authenticating in the API (https://developers.didomi.io/api/introduction/authentication)
const headers = {
Authorization: `Bearer ${token}`,
v: "2",
};
const client = {
get: bent("GET", BASE_URL, "json", headers),
patch: bent("PATCH", BASE_URL, "json", headers),
post: bent("POST", BASE_URL, "json", headers, 201),
};
(async () => {
console.log("Getting the latest draft config ...");
let {
data: [draftConfiguration],
} = await client.get(
`/widgets/notices/configs?notice_id=${noticeId}&deployed_at=null`
);
console.log("Patching consent duration to 6 months");
draftConfiguration = await client.patch(
`/widgets/notices/configs/${draftConfiguration.id}`,
{
consent_duration: 6,
consent_duration_unit: "months",
}
);
console.log(
`The configuration has a consent duration of ${draftConfiguration.consent_duration} ${draftConfiguration.consent_duration_unit}`
);
// prints: The configuration has a consent duration of 6 months
console.log("Enabling CPRA for California, United States");
draftConfiguration.regulation_configurations.push({
regulation_id: "cpra",
is_default_regulation_config: true,
geo_locations: ["US_CA"],
});
draftConfiguration = await client.patch(
`/widgets/notices/configs/${draftConfiguration.id}`,
draftConfiguration
);
// Check enabled regulations.
const enabledRegulations = draftConfiguration.regulation_configurations
.filter((rc) => rc.is_default_regulation_config)
.map((rc) => rc.regulation_id);
console.log(
`The configuration has the following regulations enabled: ${enabledRegulations.join(
", "
)}`
);
// prints: The configuration has the following regulations enabled: gdpr, cpra
// Set IAB vendor 100mercis and tappx-Vzy7mget on CPRA configuration.
let cpraConfiguration = draftConfiguration.regulation_configurations.find(
(rc) => rc.is_default_regulation_config && rc.regulation_id === "cpra"
);
cpraConfiguration.config.app = {
vendors: {
include: ["100mercis", "tappx-Vzy7mget"],
},
};
draftConfiguration = await client.patch(
`/widgets/notices/configs/${draftConfiguration.id}`,
draftConfiguration
);
cpraConfiguration = draftConfiguration.regulation_configurations.find(
(rc) => rc.is_default_regulation_config && rc.regulation_id === "cpra"
);
console.log(
`CPRA has the following vendors set: ${cpraConfiguration.config.app.vendors.include.join(
", "
)}`
);
// prints: CPRA has the following vendors set: 100mercis, tappx-Vzy7mget
})();
curl --request PATCH 'https://api.didomi.io/widgets/notices/configs/Lz97gCd6' \
--header 'Authorization: Bearer <TOKEN>' \
--header 'v: 2' \
--header 'Content-Type: application/json' \
--data-raw '{
"consent_duration": 12,
"consent_duration_unit": "months",
"regulation_configurations": [
{
"regulation_id": "cpra",
"geo_locations": ["US_CA"],
"is_default_regulation_config": true
}
]
}'
{
"custom_json": {},
"config": {
"user": {
"bots": {
"consentRequired": false
}
},
"notice": {
"position": "bottom",
"showDataProcessing": true
},
"languages": {
"default": "en",
"enabled": [
"en",
"fr"
]
}
},
"default": false,
"platform": "web",
"targets": [],
"text_mode": "approved",
"text_id": "LZJ3VTcz",
"full_atp": true,
"enable_ignore_consent_before": false,
"ignore_consent_before": null,
"negative_action": "button",
"negative_action_link": false,
"negative_action_link_format": "cross",
"negative_action_button": false,
"disagree_button_style": "primary",
"country": null,
"notice_deny_applies_to_li": true,
"preferences_deny_applies_to_li": true,
"consent_duration": 12,
"consent_duration_unit": "months",
"denied_consent_duration": 12,
"denied_consent_duration_unit": "months",
"denied_consent_duration_custom": false,
"cross_device_enabled": false,
"cross_device_timeout": 3000,
"gcm_enabled": false,
"gcm_set_default_status": true,
"gcm_data_layer_name": null,
"gcm_analytics_default_status": false,
"gcm_ads_default_status": false,
"gcm_functionality_default_status": true,
"gcm_personalization_default_status": true,
"gcm_security_default_status": true,
"template_id": null,
"regulation_configurations": [
{
"id": "R4hZbHwe",
"regulation_id": "gdpr",
"is_default_regulation_config": true,
"geo_locations": [
"AD",
"AT",
"BE",
"BG",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GF",
"GG",
"GI",
"GP",
"GR",
"HR",
"HU",
"IE",
"IS",
"IT",
"JE",
"LI",
"LT",
"LU",
"LV",
"MC",
"MF",
"MQ",
"MT",
"NL",
"NO",
"PL",
"PT",
"RE",
"RO",
"SE",
"SI",
"SK",
"SM",
"VA",
"YT"
],
"regulation_settings": {},
"config": {
"app": {
"vendors": {
"iab": {
"all": false,
"stacks": {
"auto": true
},
"enabled": true,
"version": 2
},
"include": [
"googleana-4TXnJigR",
"google"
]
}
},
"preferences": {
"categories": [
{
"type": "purpose",
"purposeId": "cookies"
},
{
"type": "purpose",
"purposeId": "measure_content_performance"
},
{
"type": "purpose",
"purposeId": "create_ads_profile"
},
{
"type": "purpose",
"purposeId": "create_content_profile"
},
{
"type": "purpose",
"purposeId": "improve_products"
},
{
"type": "purpose",
"purposeId": "market_research"
},
{
"type": "purpose",
"purposeId": "measure_ad_performance"
},
{