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 mains concept of Preference Management Platform product (1). 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 (2). Next, we will connect the dots between user consent collected in your widgets or through our API and the Configuration Tree (3). Finally, we will provide recommendations on how to read the preferences given by your end-users (4).
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.
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.
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.
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
Custom customer data questions
Privacy policies, programmes and certifications
Access to privacy rights information
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.
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 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.
For more information regarding Consents and Preferences, please check our dedicated documentation.
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.