Didomi - Developers documentation
  • Introduction
  • SDKs
    • Introduction
    • Web SDK
      • Getting started
      • Tags and vendors management
        • Tags management
          • Events & Variables
            • Deprecated
            • Custom events
          • Tag managers
            • Adobe Launch/DTM
            • Eulerian
            • Google Tag Manager
              • Configure the Didomi / GTM integration
              • Didomi's GTM template
            • Tealium
            • Other tag managers
        • Custom Didomi <script> tags
        • Third-party integrations
          • Google Ad Manager / AdSense
            • GDPR via Non-Personalized Ads
              • Share consent and load/refresh ads
              • Share consent without loading or refreshing ads
            • US states laws
          • Google Consent Mode V2
          • Kameleoon
          • Piano Analytics (AT Internet)
          • Prebid
            • GDPR via IAB TCF
            • US states laws
          • Salesforce DMP (Krux)
        • IAB frameworks
        • Programmatic API
      • Configuration
        • Bots (SEO & Performance tools)
        • Configuration by URL
        • Cookies and storage
        • Custom domains for events
        • Notice
          • Behavior
          • Interactions
          • Look and feel
        • Preferences
        • Theme
      • AB tests
      • Custom domain
        • Domain delegation
        • Reverse proxy
      • Share consents between domains
      • Share consents across devices
      • Pass user choices in query string
      • Serve Didomi assets from your domain
      • Reference
        • API
          • Deprecated
        • Events
      • Performance
    • Mobile and TV SDKs
      • Android and Android TV
        • Setup
        • Logging
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • iOS and tvOS
        • Setup
        • Logging
        • App Tracking Transparency (iOS 14.5+)
        • Reference
          • API
            • Deprecated
          • Events
        • Versions
      • Unity
        • Setup
        • Reference
        • Versions
        • Troubleshooting
      • React Native
        • Setup
        • Reference
          • Deprecated
        • Versions
      • Flutter
        • Setup
        • Reference
        • Versions
      • Consent notice
        • Getting started
        • Customize the notice
        • Customize the preferences popup
        • Customize the theme & UI
        • Load notice by ID
      • Third-party SDKs
      • Share consents across devices
      • Share consent with WebViews
      • Google Consent Mode v2
      • FAQ
    • AMP SDK
      • Blocking Behaviors
        • Load immediately on page load
        • Load only after consent (positive or negative)
        • Load only after positive consent
      • Consent status for vendors
    • Help & Support
  • API
    • Introduction
      • Authentication
      • Errors
      • Pagination
      • Filters
      • Caching
      • Rate limiting
      • Quotas
      • Translations
    • Data Manager
      • Regulations
      • Configuration Tree
      • Purposes
        • Purposes & Vendors Numerical IDs
      • Preferences Library
      • User Rights
    • Widgets
      • Consent notices
        • Notices
        • Configurations
        • Multi-Regulation Configurations
          • Migration of Existing Notices and API Updates
        • Deployments
        • Tutorials
          • Create and publish a consent notice
          • Create and publish a multi-regulation consent notice
      • Privacy widgets
        • Create a widget
        • Retrieve widgets
        • Edit a widget
          • Content & Design
            • Themes & Shapes
            • Components
              • auth
              • dsar_form
              • footer
              • header
              • preference
              • preference_value
              • save
              • section
              • sections
            • Options
          • Purposes & preferences
          • Settings
        • Deploy a Widget
          • Use your own subdomain
          • Use your own domain
          • Implement an embeddable widget on your website
        • Authentication
          • Manage authentication providers
          • Authenticate your end-user
        • Archive a widget
        • Headless widgets
          • Public Methods
          • Custom elements
          • Custom events
          • Event listeners
        • Tutorial
          • Launch a Preference Center from a mobile app
    • Compliance Reports
      • Properties
      • Reports
      • CSV format reference
      • Websites
    • Consents and Preferences
      • Events
        • Generate IAB TCF consent string
      • Links
      • Proofs
      • Tokens
      • Secrets
      • Users
      • Tutorial
        • Collect and operate data
    • Privacy Requests
      • Requests
      • Notes
      • Links
      • Emails
  • Integrations
    • Introduction
      • Quotas
    • Generic integrations
      • Batch export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
        • Exported data
          • Notices consents
        • Logs
      • Webhooks
      • Batch import
      • Analytics export
        • Destinations
          • AWS S3 Bucket (owned by Didomi)
          • GCP Storage Bucket
    • Third-party apps
      • CMP integrations
        • Didomi-mParticle integration for your CMP
        • Deploy Didomi’s SDK for your Adobe Commerce website
      • Preference Management Platform integrations
        • Actito
        • Adobe Campaign Classic
        • Adobe Experience Cloud
        • Adobe Marketo Engage
        • Adobe Source Connector
        • Braze
        • Dotdigital
        • Hubspot
        • Mailchimp
        • Microsoft Dynamics 365
        • Salesforce Marketing Cloud
        • Salesforce Sales & Service Cloud
        • Selligent
        • Brevo (ex Sendinblue)
    • Tutorials
      • Configure a HTTP webhook
      • Configure a batch export
      • Configure an analytics export
    • Emailing
      • Configurations
        • Actito Email
        • Actito SMS
        • Adobe Campaign Classic
        • Adobe Campaign Standard
      • Emails
        • Templates
        • Manage your templates
Powered by GitBook
On this page
  • Concepts
  • Entities VS Selected entities
  • How is the user consent linked to my configuration tree?
  • Is the consent value of a parent automatically propagated down to its children?
  • Get a Configuration Tree
  • Edit your Configuration Tree
  • Add a purpose into your Configuration Tree
  • Add a preference into your Configuration Tree
  • Delete a SelectedPurpose
  • Delete a SelectedPreference
  • Delete multiple SelectedPreferences
  1. API
  2. Data Manager

Configuration Tree

PreviousRegulationsNextPurposes

Last updated 1 year ago

The Configuration Tree is the core of the Preference Management Platform (PMP).

The PMP allows you to collect your users' preferences regarding communications, motivations, interests or any marketing use cases.

The PMP is based on a unique Configuration Tree on which you can add purposes and preferences. You also have the possibility to customize your widget.

Didomi's PMP empowers the collect of your users' preferences. You can then use these to establish your marketing strategies. The PMP allows you to centralize your users' preferences, which you can also integrate with your CRM and marketing automation tools.

Before we deep dive into what you can actually do with our API, let's walk you through the main concepts of the Preference Management Platform.

First of all, we will define the main concepts of Preference Management Platform product . Secondly, we will detail the relationship between entities created in your Data Manager or in your Preference Library and the selected entities you add within your Configuration Tree in order to be used in your widgets . Next, we will connect the dots between user consent collected in your widgets or through our API and the Configuration Tree . Then, we will provide recommendations on how to read the preferences given by your end-users . And finally, we will detail how you can manage this Configuration Tree ( & ).

Concepts

Widgets

A widget is an end-user facing form used to collect preferences.

A widget is based on the unique Configuration Tree defined at the organization level. It exposes end-users to a part or to all the purposes and preferences defined in the Configuration Tree.

For each widget, you can customize the color theme, shapes and content to fit your business and design needs.

Configuration Tree

Preference Management Platform is based on a unique configuration: the Configuration Tree. This is the data model used to guarantee the consistency of your data at all times, and on several Widgets.

The configuration is built on 2 types of entities: purposes and preferences to ensure GDPR compliance. The purposes describe WHY a company/organization collects data and preferences allow a more granular choice to be offered to the user for a given purpose.

Purposes that can be added into your Configuration Tree come from your Data Manager. There can be several preferences per purpose and preferences can be nested within other preferences.

Purpose

A Purpose is WHY a company/organization processes a personal data.

Personal data a company/organization may process depends on the legal reason for processing a personal and the intended use.

When a company obtains its clients’ personal data, it should explain in clear and plain language

  • why it needs the data,

  • how it will be using it,

  • and how long it intends to keep it.

The processing should be tailored in a way that respects the key data protection principles.

Preference

A Preference is an opportunity to collect information about user's intentions, motivations and interests.

Each preference can be added to one or multiple purpose(s) to offer a more granular choice to the user.

Preferences should match with different marketing use cases. Some examples:

  • Topic and content choices

  • Frequency options

  • Custom customer data questions

  • Privacy policies, programmes and certifications

  • Access to privacy rights information

Value

A Value is a choice offered within a question (preference).

Each preference has one or several choices (values) and you can define for each if your end-users can make one or multiple choices.

Preferences Library

A Preferences Library is a set of re-usable preferences.

Each preference created in Preferences Library can be used several times allowing a more granular choice to be offered to the user for given purposes.

A collection of preferences facilitate analysis of user's choices made on your Widgets.

Entities VS Selected entities

Purposes and Preferences

Purposes and Preferences can be inserted in your configuration tree. When you add one of those entities in your tree, we will create what we call a selected entity. It is a reference of the original entity which will allow you to have unique IDs as well as keep the order of your entity in the tree. All other information are not duplicated which means that the content (name and description) of a selected entity is always coming from its original entity. It allows you to easily change a content for all your entities in one place.

Values

Values work differently since they are always linked to a preference. Which means we don’t create a selected entity for values as they are unable to work independently from a preference. You can compare them to questions and answers, you will always need to know the question for an answer to make sense. Therefore, the uniqueness is based on the combination of the parent ID (selected preference) and the ID of the value.

How is the user consent linked to my configuration tree?

First of all, let’s understand what can be stored in a consent and how is it structured. We can collect consents for purposes which are stored as a boolean value and for preferences which can contain multiple values.

Since original entities can be reusable multiple times in the configuration tree, the IDs we are interested in here are the IDs of the selected purposes as well as the selected preferences values.

Use case of Marketing communications

I want to ask my customer how do they want to be contacted for marketing communication. I also want to know how frequently for SMS and Email.

First, I create my purpose, preferences and values. Once they are in my library, I will assemble my configuration tree. The result should look as below.

You can see here that for each purpose and preference, I have a unique ID as well as IDs for each values of a preference. This is the ones we will use in the consent.

A widget showing my configuration tree has been created and deployed, I want my users to start giving consents.

A customer logs in and decides to get notified for marketing communication by SMS quarterly as well as by Push notification.

The consent information contains the IDs of the selected purposes with their boolean values as well as, for each purpose, a flat structure of the selected preferences with at least one values enabled and the corresponding values IDs enabled for this preference.

Here we retrieve the information that: I have a consent for the purpose marketing communication (marketing-kfDxBxLe).

For that purpose, I have a consent for the preference communication channels (b6Aqki3N) SMS (WNtiKXW4) and Push notification (KzxBJpPq) and finally a consent for the Frequency linked to the SMS channel (CYiK38JR) for quarterly communication (NRYPjGEb).

To avoid a complex object structure, the consent is flat for preferences. You will need your configuration tree to retrieve the correct nesting.

As mentioned above, a value cannot live independently from a preference, as an answer cannot live without a question. Therefore, please keep in mind that a value ID is not unique in the Configuration Tree and a valid consent is the addition of a selected preference and a value associated to it.

Is the consent value of a parent automatically propagated down to its children?

No, each values are independent. If a purpose is disabled, we will return the values of its children if there are enabled in the consent. It is up to you to decide how to use the different consent values in your integrations and condition on multiple consent values.

There are some use cases where you can ask yourself if the user has given his consent or not. Here’s some examples with our recommandations.

Only the most nested preference value is selected

Let’s take the Marketing communication use case again. This screenshot could be an example of a Preference Center.

In a Single purpose widget embedded on your website, you could ask the following question in this awful way: “How often do you want to receive SMS about our Marketing communications ?”.

Here, we can reasonably say that you informed enough your user about what he is going to consent to. If the user has not selected values of the parent preferences and has selected one Frequency preference’s values, you can safely consider your user has consented to receive SMS of your Marketing communications.

A preference value is selected but consent is negative

In this example, the end-user could have made choices on some of your Single purpose widget. In these widgets, he has answer positively to receive SMS every week and even Push notifications.

In his Preference Center or even in another Single purpose widget, your end-user has unfortunately said “no” to Marketing communications.

We recommend you to use the No as an answer for all children even if they have been selected “positively”. Here, even if the end-user aims to receive SMS every week, he does not want to receive Marketing Communication.

Get a Configuration Tree

To retrieve data of your Configuration Tree, send a GET request on /config-trees.

GET https://api.didomi.io/config-trees?organization_id=YOUR_ORG_ID

[
  {
    "id": "String",
    "created_at": "Date",
    "updated_at": "Date",
    "organization_id": "String",
    "selected_purposes": [
      {
        "id": "string",
        "created_at": "Date",
        "updated_at": "Date",
        "purpose": {
          "id": "String",
          "organization_id": "String",
          "description": {},
          "details": {}
        },
        "purpose_id": "String",
        "configuration_tree_id": "String",
        "order": 0,
        "selected_preferences": [
          {
            "id": "String",
            "created_at": "Date",
            "updated_at": "Date",
            "selected_preferences": [
              {
                "id": "String",
                "created_at": "Date",
                "updated_at": "Date",
                "selected_preferences": [
                  {}
                ],
                "parent_id": "String",
                "preference": {
                  "id": "String",
                  "created_at": "Date",
                  "updated_at": "Date",
                  "name": {
                    "en": "String"
                  },
                  "description": {
                    "en": "String"
                  },
                  "organization_id": "String",
                  "type": "single",
                  "values": [
                    {
                      "id": "String",
                      "created_at": "Date",
                      "updated_at": "Date",
                      "name": {
                        "en": "String"
                      },
                    }
                  ]
                },
                "parent_selected_purpose_id": "String",
                "parent_preference_value_id": "String",
                "order": 0,
                "configuration_tree_id": "String"
              }
            ],
            "parent_id": "String",
            "preference": {
              "id": "String",
              "created_at": "Date",
              "updated_at": "Date",
              "name": {
                "en": "String"
              },
              "description": {
                "en": "String"
              },
              "organization_id": "String",
              "type": "single",
              "values": [
                {
                  "id": "String",
                  "created_at": "Date",
                  "updated_at": "Date",
                  "name": {
                    "en": "String"
                  },
                  "selected_preferences": [
                    {}
                  ]
                }
              ]
            },
            "parent_selected_purpose_id": "String",
            "parent_preference_value_id": "String",
            "order": 0,
            "configuration_tree_id": "String"
          }
        ]
      }
    ]
  }
]

Optional query parameters:

  • $limit: number of max results to return

  • $skip: number of results to skip

  • $sort: represents sorting options. Accepts date properties to sort (created_at, updated_at) as keys and -1 or 1 for sort direction as value.

    • $sort[created_at]=1 or -1

    • $sort[updated_at]=1 or -1

  • $with[]: list of entity names to join, values possible : purpose, preference

    • $with[]=purpose

    • $with[]=preference

Edit your Configuration Tree

Add a purpose into your Configuration Tree

To add a purpose into your Configuration Tree, send a POST request on /config-trees/{configuration_tree_id}/selected-purposes.

POST https://api.didomi.io/config-trees/{configuration_tree_id}/selected-purposes?organization_id=YOUR_ORG_ID

{
  "purpose_id": "YOUR_PURPOSE_ID",
  "order": 0
}

Add a preference into your Configuration Tree

To add a preference into your Configuration Tree, send a POST request on /config-trees/{configuration_tree_id}/selected-preferences.

POST https://api.didomi.io/config-trees/{configuration_tree_id}/selected-preferences?organization_id=YOUR_ORG_ID

{
  "preference_id": "string",
  "parent_selected_purpose_id": "string",
  "order": 0,
  "parent_id": "string",
  "parent_preference_value_id": "string"
}
Element
Required
Description

configuration_tree_id

Yes

id of the Configuration Tree

organization_id

Yes

id of the organization

preference_id

Yes

id of the preference

parent_selected_purpose_id

Yes

id of the SelectedPurpose the SelectedPreference belongs to.

order

Yes

Order of SelectedPurpose in Configuration Tree

parent_id

Yes, if nesting inside a preference value

id of the SelectedPreference the nested SelectedPreference belongs to.

parent_preference_value_id

Yes, if nested inside a preference value

id of the value the nested SelectedPreference belongs to.

Delete a SelectedPurpose

To delete a purpose from your Configuration Tree, send a DELETE request on /config-trees/{configuration_tree_id}/selected-purposes/{id}.

All SelectedPreferences nested inside the SelectedPurpose will be removed too.

DELETE https://api.didomi.io/config-trees/{configuration_tree_id}/selected-purposes/{selected_purposes_id}?organization_id=YOUR_ORG_ID

Delete a SelectedPreference

To delete a preference from your Configuration Tree, send a DELETE request on /config-trees/{configuration_tree_id}/selected-preferences/{id}.

All SelectedPreferences nested inside the SelectedPreference will be removed too.

DELETE https://api.didomi.io/config-trees/{configuration_tree_id}/selected-preferences/{selected_preferences_id}?organization_id=YOUR_ORG_ID

Delete multiple SelectedPreferences

To delete multiple preferences from your Configuration Tree, send a DELETE request on /config-trees/{configuration_tree_id}/selected-preferences?id[]={id}.

All SelectedPreferences nested inside the SelectedPreference will be removed too.

DELETE https://api.didomi.io/config-trees/{configuration_tree_id}/selected-preferences/?organization_id=YOUR_ORG_ID&id[]=ID

id query params have to follow array format id[] pattern.

For more information regarding Consents and Preferences, please check our dedicated .

To retrieve purposes from you Data Manager, you can send a GET request on .

To retrieve preferences from you Preferences Library, you can send a GET request on .

documentation
/metadata/purposes
/preferences
preferences
(1)
(2)
(3)
(4)
5
6
Concepts
Entities VS Selected entities
Link between user consent and the Configuration Tree
Is the consent value of a parent automatically propagated down to its children?
Get a Configuration Tree
Edit your Configuration Tree