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