Multi-Regulation Configurations

This page explains how consent notices support multiple regulations that are displayed in different countries and regions, and how to work with those notice configurations.

A multi-regulation configuration is a Configuration (see Configurations) that enables a single notice to support multiple regulations depending on the country and region of origin for the visitor. For example, EU visitors will see a GDPR version of the notice while visitors from California (US) will see a CPRA version instead, assuming that the notice has been configured to support both regulations either in the console or via the API.

The introduction of a regulation_configurations property on the Configuration enables multi-regulation notices. One Configuration has many Regulation-Configurations.

The multi-regulation approach is not yet compatible with Cross-device and Batch export features. For those features, the user consent will be considered as GDPR consent.

Regulation-Configurations

A Regulation-Configuration has a set of notice configuration properties of the Configuration that are nullable by default. This enables the configuration of specific properties that will override the parent Configuration settings.

The Regulation-Configuration entities are not managed directly but through the Configuration entity via the regulation_configurations property (see here).

Specifying Where to Show a Specific Regulation (Geo-locations)

Each Regulation-Configuration entity defines a list of countries and/or regions that the regulation applies to which are set through the geo_locations array field.

Country Codes

In the case of a targeting a country, these are comprised of the 2-letter ISO 3166-1 alpha-2 country codes (e.g., "FR" for France).

Region Codes

In the case of a region within a country, a multipart ISO and region code string separated by an underscore is used (e.g., "US_CA" for United States, California). The region substring contains a code (up to three characters) that represent the viewer's region. The region is the first-level subdivision (the broadest or least specific) of the ISO 3166-2 code.

Global Default

The wildcard * serves as a "global" geo-location, indicating which configuration should be loaded when no specific configuration for a given region is configured.

Geo-locations

Geo-location configuration constraints:

• Default regulation configurations (those Regulation-Configuration entities where is_default_regulation_configuration is true) cannot have overlapping geo-locations. ie. Cannot assign US to CPRA if it is assigned to GDPR.

• Non-default regulation configurations must be a subset of their regulation default configuration geo-locations. ie. Select a subset of geo-locations to override certain configurations.

Note: see here the list of supported regulations and their default geo_locations.

Putting it Together: Creating a Notice with Multiple Regulations

A Configuration entity can have multiple Regulation-Configuration entities per regulation. Every regulation possesses a foundational configuration (identified by the is_default_regulation_config field), along with optional supplementary configurations that build upon by modifying particular properties for designated geographic areas.

A practical instance of this scenario involves the default GDPR notice setup. This setup has a base Regulation-Configuration aimed at the European Union, with additional Regulation-Configuration entities that carry specific setting overrides for Italy and France. Italian regulation necessitates the display of an X button to close the notice, while the French one mandates the presence of a Disagree and close button.

A multi-regulation Configuration can then be pictured as a tree, where the Configuration entity is the root. For example:

• Configuration

  • Regulation-Configurations

    • GDPR base

      • GDPR France override

      • GDPR Italy override

    • CPRA base

Settings present on the Configuration entity serve as cross-regulation default configurations. Settings at the Regulation-Configuration are nullable and will only override Configuration settings if present.

For instance, consider the standard GDPR setup in combination with CPRA ; GDPR has 3 variants, a default configuration for all EU countries except for Italy and France, and separate configurations for Italy and France that each have their own country-specific notice settings.

Sample Multiple Regulation Configuration

{
  "id": "jAbmaPzN",
  
  "config": {
    "app": {
      "vendors": {
        "include": ["vendor A"]
      },
      ... other config fields
    }
  },
  
  ... other fields
  
  "negative_action_link_format": "cross",
  "negative_action_link": false,
  "negative_action_button": false,
  "regulation_configurations": [
    {
      "id": "W37f3Bmd",
      "notice_config_id": "jAbmaPzN",
      "regulation_id": "gdpr",
      "is_default_regulation_config": true,
      "geo_locations": ["ES", "FR", "DE", "IT", ...EU],
      "config": {
        "app": {
          "vendors": {
            "include": ["vendor A", "vendor B"]
          },
          ... other config fields
        }
      },
    
      ... other fields
    
      "negative_action_link_format": null,
      "negative_action_link": null,
      "negative_action_button": null
    },
    {
      "id": "Vaz4eBgf",
      "notice_config_id": "jAbmaPzN",
      "regulation_id": "gdpr",
      "is_default_regulation_config": false,
      "geo_locations": ["IT"],

      ... other fields

      "negative_action_link_format": "cross",
      "negative_action_link": true,
      "negative_action_button": false
    },
    {
      "id": "hrQLN24J",
      "notice_config_id": "jAbmaPzN",
      "regulation_id": "gdpr",
      "is_default_regulation_config": false,
      "geo_locations": ["FR"],

      ... other fields

      "negative_action_link_format": "text",
      "negative_action_link": false,
      "negative_action_button": true
    },
    {
      "id": "CbxWneYt",
      "notice_config_id": "jAbmaPzN",
      "regulation_id": "cpra",
      "is_default_regulation_config": true,
      "geo_locations": ["US_CA"],

      ... other fields
      
      "config": {
        "app": {
          "vendors": {
            "include": ["vendor C", "vendor D"]
          },
          ... other config fields
        }
      },

      "negative_action_link_format": null,
      "negative_action_link": null,
      "negative_action_button": null
    }
  ]
}

Modifying Existing Regulation-Configurations

Regulation-Configurations are managed through the Configuration.regulation_configurations array.

When updating the Configuration, existing objects within the regulation_configurations array that have an ID field will be modified, while those without an ID will be created. Existing but absent Regulation-Configurations will be unmodified and subsequently included in the response.

Overridable Properties

The following properties may be overridden by Regulation-Configurations:

interface RegulationOverridableFields {
  enable_ignore_consent_before: boolean | null;
  ignore_consent_before: string | null;
  negative_action_link: boolean | null;
  negative_action_link_format: 'text' | 'cross' | null;
  negative_action_button: boolean | null;
  disagree_button_style: 'primary' | 'secondary' | null;
  notice_deny_applies_to_li: boolean | null;
  preferences_deny_applies_to_li: boolean | null;
  consent_duration: number | null;
  consent_duration_unit: 'seconds' | 'day' | 'months' | null;
  denied_consent_duration: number | null;
  denied_consent_duration_unit: 'seconds' | 'day' | 'months' | null;
  denied_consent_duration_custom: boolean | null;
  cross_device_enabled: boolean | null;
  cross_device_timeout: number | null;
  gcm_enabled: boolean | null;
  gcm_set_default_status: boolean | null;
  gcm_analytics_default_status: boolean | null;
  gcm_ads_default_status: boolean | null;
  gcm_functionality_default_status: boolean | null;
  gcm_personalization_default_status: boolean | null;
  gcm_security_default_status: boolean | null;
  gcm_data_layer_name: string | null;
  full_atp: boolean | null;
}

Configurations stored in the config object are combined (merged) on a path basis. As the Configuration and Regulation-Configuration entities are merged to generate the final output configuration, the following paths are replaced (if present) over the parent configuration.

app.essentialPurposes
app.vendors.include
app.vendors.iab
theme.fullscreen
theme.notice.titleTextSize
theme.notice.titleAlignment
theme.notice.titleTextColor
theme.notice.descriptionTextSize
theme.notice.descriptionAlignment
theme.notice.descriptionTextColor
notice.daysBeforeShowingAgain
notice.enableBulkActionOnPurposes
notice.position
notice.content.title
notice.content.notice
notice.content.manageSpiChoices
notice.content.popup
notice.content.notice
notice.content.dismiss
notice.content.deny
notice.content.learnMore
preferences.categories
preferences.description
preferences.sectionTitle
preferences.enableAllButtons
preferences.content.title
preferences.content.text
preferences.content.agree
preferences.content.disagree
preferences.content.viewAllPartners
preferences.content.agreeToAll
preferences.content.disagreeToAll
preferences.content.save
preferences.content.subText
preferences.content.textVendors
preferences.content.authorizeVendors
preferences.content.blockVendors
preferences.content.subTextVendors

Sample Override Scenario Logic

Let's consider an example focusing on the selected vendors for a notice within the array located at app.vendors.include.

We want a notice:

• that is configured for GDPR , CPRA and LGDP

• with base fallback vendors for the notice to be A and B.

• with a GDPR exception, for Germany, so as to additionally include vendor C.

• with CPRA configured to a different set of vendors: D and E.

To achieve the desired setup consider the following configuration:

To set the base fallback vendors for the notice, irrespective of the regulation, configure:

Configuration.config.app.vendors.include = [A, B]

To enable GDPR for the notice we would need a default GDPR Regulation-Configuration (included on every notice by default covering EU countries). There is no need to specify vendors on the default GDPR Regulation-Configuration as we would like them to fallback to [A, B] (set on the Configuration as a cross-regulation fallback configuration).

To configure the Germany exception, we would need an additional non default GDPR Regulation-Configuration with geo locations set as [DE] where Regulation-Configuration.config.app.vendors.include = [A, B, C].

To enable LGPD we would need a default LGDP Regulation-Configuration with geo locations set to [BR], no need to specify vendors as we would like the vendor configuration to fallback to [A, B], which were already set on the Configuration .

Finally, to configure CPRA, we would need a default CPRA Regulation-Configuration with geo locations set to [US_CA]. As we want a different set of vendors for CPRA we would need to set Regulation-Configuration.config.app.vendors.include = [D, E]

Summarising, the configuration would look like this:

Configuration:
    config.app.vendors.include = [A, B]

GDPR Regulation Configuration:
    is_default_regulation_config: true
    geo_locations = [DE, ES, FR, IT, ...]

GDPR Regulation Configuration:
    is_default_regulation_config: false
    geo_locations = [DE]
    config.app.vendors.include = [A, B, C]

LGDP Regulation Configuration:
    is_default_regulation_config = true
    geo_locations = [BR]

CPRA Regulation Configuration:
    is_default_regulation_config = true
    geo_locations = [US_CA]
    config.app.vendors.include = [D, E]

When published, vendor configuration per geo location will be as follows:

DE: A, B, C
ES: A, B
IT: A, B
FR: A, B
...all other EU countries: A, B
BR: A, B
US_CA: D, E

Note: LGDP did not specify vendors resulting in its vendors having to fallback to configuration present in the Configuration

See the API documentation for more details on using our API to publish a configuration.