Configurations

A notice configuration determines the full behavior of a consent notice, including the platform that it applies to, its targeted properties, and all the configuration options for the notice (texts, buttons, etc.).

For a given notice, the full history of configurations are kept:

• The current draft configuration that is not yet applied to the notice and can be modified to prepare for future publishing.

• The previous published configurations that are kept for audit and compliance purposes and cannot be modified.

The /widgets/notices/configs endpoint of the API exposes the notice configurations managed by Didomi for your organizations. For a full reference of the endpoint and the resources that it returns, visit https://api.didomi.io/docs/.

Draft configuration

The notice configuration that can be modified before publishing is called "draft" and is the notice configuration that is not yet deployed. If you want to modify the configuration of your notice on your websites/apps, you must first modify the draft configuration and then publish it.

Get the current draft configuration for a notice

The current draft configuration for a notice is marked with null as the value for its deployed_at field.

To identify the current draft configuration, get all the notice configurations and find the one that has deployed_at = null.

Example

GET https://api.didomi.io/v1/widgets/notices/configs
    ?organization_id=<Organization ID>
    &notice_id=<Notice ID>

{
    "total": 2,
    "limit": 100,
    "skip": 0,
    "data": [
        {
            "deployed_at": "2020-09-01T21:26:50.629Z",
            "custom_json": { ... },
            "config": { ... },
            "default": false,
            "platform": "web",
            "targets": [],
            "text_mode": "approved",
            "text_id": "W37f3Bmd",
            "full_atp": false,
            "enable_ignore_consent_before": false,
            "ignore_consent_before": null,
            "negative_action": null,
            "disagree_button_style": "secondary",
            "country": null,
            "notice_deny_applies_to_li": false,
            "preferences_deny_applies_to_li": true,
            "consent_duration": 12,
            "consent_duration_unit": "months",
            "notice_id": "GG2rdGfN",
            "organization_id": "didomi",
            "id": "tiYx2MWn",
            "created_at": "2020-07-23T09:14:26.264Z",
            "updated_at": "2020-09-01T21:26:50.701Z",
            "version": 0
        },
        {
            "deployed_at": null,
            "custom_json": { ... },
            "config": { ... },
            "default": false,
            "platform": "web",
            "targets": [
                "some.domain.test.exmpl"
            ],
            "text_mode": "approved",
            "text_id": "W37f3Bmd",
            "full_atp": false,
            "enable_ignore_consent_before": false,
            "ignore_consent_before": null,
            "negative_action": null,
            "disagree_button_style": "secondary",
            "country": null,
            "notice_deny_applies_to_li": false,
            "preferences_deny_applies_to_li": true,
            "consent_duration": 12,
            "consent_duration_unit": "months",
            "notice_id": "GG2rdGfN",
            "organization_id": "didomi",
            "id": "2fcjz7Cw",
            "created_at": "2020-09-01T21:26:50.724Z",
            "updated_at": "2021-03-24T15:56:50.461Z",
            "version": 0
        }
    ]
}

In this example, the second configuration (with ID 2fcjz7Cw) is the current draft and can be modified to prepare for publishing.

See the API documentation for more details on using our API to get notice configurations.

Modify the draft configuration

To update the configuration of your consent notice, you must update the draft configuration and then publish it. To update the draft configuration send a PATCH request to the current draft configuration.

Example

To modify the draft configuration, send a PATCH request with an updated configuration. Example for switching the notice to a mobile notice with a consent duration of 6 months:

PATCH https://api.didomi.io/v1/widgets/notices/configs/7bKP4CRr

{
    "platform": "app",
    "consent_duration": 6,
    "consent_duration_unit": "months"
}

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

What is the config field?

The full configuration of a notice is split between the config field and the other fields on the configuration object:

• The config field follows the format documented for the configuration of the SDKs in our SDKs configuration section.
• The other fields of the configuration are documented in our API documentation.

Didomi is in the process of transforming the config field into separate fields on configurations and will do so in a backward-compatible manner. The config field will eventually be deprecated as it proved complex to work with.

Published configurations

Configurations that are already published (or "deployed") are marked with their publishing date in the deployed_at field. A configuration that is already published cannot be modified so that it can be used as proof of how consent was collected at a given time.

Publish a draft configuration

Only draft configurations can be published. A draft configuration is marked as deployed once it is published and cannot be published or modified anymore.

To publish the current draft configuration, create a deployment for that configuration by sending a POST /widgets/notices/deployments request for that specific configuration.

After a configuration is published, the publishing date is set in its deployed_at field and that configuration cannot be modified or published anymore. A new draft configuration is automatically created for the notice as a copy of the latest published configuration. To make further changes to the notice configuration, get the new draft configuration and modify it.

Example

POST https://api.didomi.io/v1/widgets/notices/deployments

BODY
{
    "notice_id": "GG2rdGfN",
    "organization_id": "didomi",
    "production_config_id": "2fcjz7Cw",
    "message": "Description of changes included in my deployment"
}

The production_config_id should be the ID of the draft config you are publishing. message is a text field that can be used to indicate information on what changes are included in your deployment.

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