Migration of Existing Notices and API Updates

This page describes how Didomi migrated pre-existing Configurations to support multiple regulations, and important changes to the Notice and Configuration API endpoints.

Originally, configuration entities were solely and implicitly related to GDPR. In order to manage these pre-existing entities with the multi-regulation version of the API, they must be migrated to adhere to the updated data model.

Migrations are handled by Didomi and do not require any action on behalf of our customers and should be transparent, although to begin working with the new multiple regulation notice configurations, you will need to make some changes to how you create and update notice configurations, see Create and publish a multi-regulation consent noticefor more details.

What will happen to existing notice configurations once they are migrated to support multi-regulations?

Upon migrating an organization to support multiple regulations, a base GDPR Regulation-Configuration is created for each draft Configuration, incorporating all fields from the Configuration.

Geo-locations for the newly created GDPR Regulation-Configuration are set to ["*"] if Configuration.config.app.gdprAppliesGlobally is true. Otherwise, they include European GDPR-regulated countries, as well as any additional countries specified in Configuration.config.regulations.gdpr.additionalCountries.

How will existing API integrations behave?

Existing Notice and Configuration API integrations will be supported in a backward compatible way, although it will be eventually required to upgrade integrations as the legacy API will be deprecated at some point. Continuing to work with the older versions of some endpoints will create a slightly different experience than what is currently shown in the console, and in order to work with the new regulations, you will need to follow the steps outlined in this document to modernize your API integration(s) when working with notices and configurations.

When an organization is migrated to support multiple regulations, existing API calls to the Notice and Configurations endpoints will be redirected to a backward-compatible API. This backward-compatible API serves as a proxy for data changes between the Configuration interface and the foundational GDPR Regulation-Configuration.

When persisting a Configuration object through the backward-compatible API those fields that can be configured at the Regulation-Configuration level will be forwarded to the default GDPR Regulation-Configuration . This means that changes over those fields are not applied to the actual Configuration entity, but to its default GDPR Regulation-Configuration.

Additionally, the legacy geo-configuration is mapped to the new model: Configuration.config.app.gdprAppliesGlobally and Configuration.config.regulations.gdpr.additionalCountries are converted to a list of geo-locations that is set for the deault GDPR Regulation-Configuration.

The opposite steps take place when retrieving a Configuration via the backward-compatible API. The default GDPR Regulation-Configuration is selected and any present configuration fields are overwritten over the Configuration to return. Geo-locations assigned to the default GDPR Regulation-Configuration are converted back to the legacy geo-configuration, that is, converting a list of geo-locations to Configuration.config.app.gdprAppliesGlobally and Configuration.config.regulations.gdpr.additionalCountries.

When creating a Notice, a draft Configuration is created. Existing integrations will lack the v:"2" header, so the backward-compatible API is employed using legacy Configuration defaults. Consequently, programmatically created multi-regulation notices will lack the French and Italian GDPR compliance configuration overrides.

How should I update my existing API integrations?

Notice Creation

If you create notices through the API (ie. POST /widgets/notices), you must update your API calls to include the header v:"2" on the request to access the new GDPR default configurations.

The response to POST /widgets/notices remains the same, although the underlying initial draft Configuration created for the Notice now has access to multi-regulation defaults. These defaults have been crafted to include the Italian and French GDPR configuration exceptions to comply with local requirements.

Note: The configuration created with v:"2" has 2 extra Regulation-Configurations overriding IT and FR with specific configurations regarding the negative action button. See this section for more details.

You can find samples below showing the default Configurations for notices with and without IAB presets for the web platform:

V2 Configuration for Notice created with no preset and v:"2" header
{
    "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": "W37f3Bmd",
    "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": "U9kG9jzQ",
            "regulation_id": "gdpr",
            "is_default_regulation_config": true,
            "geo_locations": [
                "AD",
                "AT",
                "BE",
                "BG",
                "CY",
                "CZ",
                "DE",
                "DK",
                "EE",
                "ES",
                "FI",
                "FR",
                "GB",
                "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-29T10:59:45.389Z",
            "updated_at": "2023-03-29T10:59:45.389Z",
            "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": "AkNMhKbQ",
            "organization_id": "test-multi-regulation-migration"
        },
        {
            "id": "ftzPx4EQ",
            "regulation_id": "gdpr",
            "is_default_regulation_config": false,
            "geo_locations": [
                "IT"
            ],
            "regulation_settings": {},
            "config": {},
            "disabled_at": null,
            "created_at": "2023-03-29T10:59:45.389Z",
            "updated_at": "2023-03-29T10:59:45.389Z",
            "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": "AkNMhKbQ",
            "organization_id": "test-multi-regulation-migration"
        },
        {
            "id": "jrtG3DYf",
            "regulation_id": "gdpr",
            "is_default_regulation_config": false,
            "geo_locations": [
                "FR"
            ],
            "regulation_settings": {},
            "config": {},
            "disabled_at": null,
            "created_at": "2023-03-29T10:59:45.389Z",
            "updated_at": "2023-03-29T10:59:45.389Z",
            "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": "AkNMhKbQ",
            "organization_id": "test-multi-regulation-migration"
        }
    ],
    "secure_cookies": false,
    "notice_id": "iVPAii2C",
    "organization_id": "test-multi-regulation-migration",
    "deployed_by": null,
    "deployed_by_type": null,
    "deployed_by_name": null,
    "deployed_at": null,
    "id": "AkNMhKbQ",
    "created_at": "2023-03-29T10:59:45.362Z",
    "updated_at": "2023-03-29T10:59:45.362Z",
    "version": 0,
    "deployed_metadata": {}
}
V2 Configuration for Notice created with no preset and without v:"2" header
{
    "custom_json": {},
    "config": {
        "app": {
            "vendors": {
                "iab": {
                    "all": true,
                    "stacks": {
                        "auto": true
                    },
                    "enabled": true,
                    "version": 2
                }
            }
        },
        "notice": {
            "content": {
                "popup": {},
                "notice": {}
            },
            "showDataProcessing": true
        }
    },
    "default": false,
    "platform": "web",
    "targets": [],
    "text_mode": "approved",
    "text_id": "W37f3Bmd",
    "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": true,
    "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": true,
    "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": "CrAKFBeA",
            "regulation_id": "gdpr",
            "is_default_regulation_config": true,
            "geo_locations": [
                "AD",
                "AT",
                "BE",
                "BG",
                "CY",
                "CZ",
                "DE",
                "DK",
                "EE",
                "ES",
                "FI",
                "FR",
                "GB",
                "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": true,
                            "stacks": {
                                "auto": true
                            },
                            "enabled": true,
                            "version": 2
                        },
                        "include": [
                            "googleana-4TXnJigR",
                            "google"
                        ]
                    }
                },
                "notice": {
                    "content": {
                        "popup": {},
                        "notice": {}
                    }
                },
                "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-29T10:42:21.072Z",
            "updated_at": "2023-03-29T10:42:21.072Z",
            "enable_ignore_consent_before": false,
            "disagree_button_style": "primary",
            "consent_duration": 12,
            "consent_duration_unit": "months",
            "denied_consent_duration": 12,
            "denied_consent_duration_unit": "months",
            "denied_consent_duration_custom": false,
            "gcm_enabled": true,
            "gcm_set_default_status": true,
            "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,
            "negative_action_link_format": "cross",
            "notice_deny_applies_to_li": true,
            "preferences_deny_applies_to_li": true,
            "version": 0,
            "negative_action_link": false,
            "negative_action_button": true,
            "gcm_data_layer_name": null,
            "full_atp": true,
            "notice_config_id": "JkpeEq3M",
            "organization_id": "test-multi-regulation-migration"
        }
    ],
    "secure_cookies": false,
    "notice_id": "Tm4xa8fM",
    "organization_id": "test-multi-regulation-migration",
    "deployed_by": null,
    "deployed_by_type": null,
    "deployed_by_name": null,
    "deployed_at": null,
    "id": "JkpeEq3M",
    "created_at": "2023-03-29T10:42:21.047Z",
    "updated_at": "2023-03-29T10:42:21.047Z",
    "version": 0,
    "deployed_metadata": {}
}
V2 Configuration for Notice created with IAB preset and v:"2" header
{
    "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": "7KzGUft3",
            "regulation_id": "gdpr",
            "is_default_regulation_config": true,
            "geo_locations": [
                "AD",
                "AT",
                "BE",
                "BG",
                "CZ",
                "DE",
                "DK",
                "EE",
                "ES",
                "FI",
                "FR",
                "GR",
                "HR",
                "HU",
                "IE",
                "IT",
                "LI",
                "LT",
                "LU",
                "LV",
                "MC",
                "MT",
                "NL",
                "PL",
                "PT",
                "RO",
                "SE",
                "SI",
                "SK",
                "SM",
                "VA",
                "GB"
            ],
            "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-04-13T12:04:43.230Z",
            "updated_at": "2023-04-13T12:04:43.230Z",
            "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": "Ujb3ejte",
            "organization_id": "iJcpp0p2n"
        },
        {
            "id": "4kzK96wb",
            "regulation_id": "gdpr",
            "is_default_regulation_config": false,
            "geo_locations": [
                "IT"
            ],
            "regulation_settings": {},
            "config": {},
            "disabled_at": null,
            "created_at": "2023-04-13T12:04:43.230Z",
            "updated_at": "2023-04-13T12:04:43.230Z",
            "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": "Ujb3ejte",
            "organization_id": "iJcpp0p2n"
        },
        {
            "id": "eRYMJHED",
            "regulation_id": "gdpr",
            "is_default_regulation_config": false,
            "geo_locations": [
                "FR"
            ],
            "regulation_settings": {},
            "config": {},
            "disabled_at": null,
            "created_at": "2023-04-13T12:04:43.230Z",
            "updated_at": "2023-04-13T12:04:43.230Z",
            "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": "Ujb3ejte",
            "organization_id": "iJcpp0p2n"
        }
    ],
    "secure_cookies": false,
    "notice_id": "ttDzp33k",
    "organization_id": "iJcpp0p2n",
    "deployed_by": null,
    "deployed_by_type": null,
    "deployed_by_name": null,
    "deployed_at": null,
    "id": "Ujb3ejte",
    "created_at": "2023-04-13T12:04:43.176Z",
    "updated_at": "2023-04-13T12:04:43.176Z",
    "version": 0,
    "deployed_metadata": {}
}

API response changes on GET endpoints

If you programmatically consume the contents of Configuration objects through any of the following endpoints:

  • GET /widgets/notices/configs/:id

  • GET /widgets/notices/configs

You will need to update the requests to include the header v:"2" to move out of the backward-compatible Configuration API. By doing so the returned Configuration will now return the regulation_configurations array.

Consumers should update their integration code to correctly consider the whole state of the Configurations by including the new regulation_configurations array.

Below find samples of a web Notice Configuration created with v:"2" and presented with and without the backward-compatible API.

Default v:"2" Configuration presented by the backward compatible API
{
    "custom_json": {},
    "config": {
        "user": {
            "bots": {
                "consentRequired": false
            }
        },
        "notice": {