Consent management
Prerequisite
Consent Management is only available on PA javascript > 6.8.
If you use mobile SDKs or PA JS < 6.8, please use legacy Privacy management methods.
What is "Consent Management"
"Consent Management" is the first building block of unified tagging methods across all Piano products.
You will be able to control the data collected and the cookies placed, according to the different legislations you refer to. All in one place for all your Piano products.
In other words, it allows you to customize your tagging thanks to a precise management of the different measurement parameters (events and properties sent, trackers used, ...), in compliance with the regulations in force.
You have two options:
- You use several Piano products and you want to manage privacy in a unified way. Then you can use our global documentation.
- You use only Piano Analytics and prefer a granular approach to privacy management. Then you can stay here.
Don't worry, a granular PA consent management setup can be easily migrated to a more global Piano setup!
Key notion
A "Consent Mode" is a state in which you can have control over various items:
- The cookies you want to set
- The events / properties you want to send
- The value your
visitor_privacy_mode
andvisitor_privacy_consent
properties will take
Basically, we can say that a Consent Mode refers to a specific purpose (under GDPR).
Thanks to the visitor_privacy_mode
and visitor_privacy_consent
, you will be able to respect a perfect data governance by applying dedicated treatments depending on the mode the data has been collected.
Consent Modes
Consent Mode | "_pcid" cookie | Visitor ID | visitor_privacy_mode | visitor_privacy_consent | Properties / events | Exclusion / Anonymization | Comment |
---|---|---|---|---|---|---|---|
opt-in | ✅ | ✅ | optin | true | all | ❌ | |
essential | ✅ | ✅ | exempt | false | some | ❌ | Requires a specific configuration as explained in our Privacy center |
opt-out | ✅ | ❌ | optout | false | some | ✅ | All events will be excluded and anonymized. More information in our Privacy Center |
custom | you decide | you decide | you decide | you decide | you decide (same base as essential mode) | ❌ | Some cookies, properties and events are included by default to a custom mode |
Each mode has by default its own rules.
You can check which storage keys (cookies), properties and events are included by default in the dedicated article.
You can also find the list of our cookies and storage keys in the Cookies & storage article.
Pre-requisite
The configuration of the Consents feature uses the global object window.pdl
, that must be defined and populated before the loading of the SDK.
<script>
window.pdl = window.pdl || {};
...
</script>
...
<script src="piano-analytics.js"></script>
Activating the Consents feature
In order to activate the Consents feature, you need to set the requireConsent
variable to true
:
window.pdl = window.pdl || {};
window.pdl.requireConsent = true;
Configure the default consent mode
In order to define the default consent mode for Piano Analytics (PA
), you need to set the consent.defaultPreset.PA
variable to the desired value (optin
by default):
window.pdl = window.pdl || {};
window.pdl.requireConsent = true;
window.pdl.consent = {
defaultPreset: {
PA: 'essential'
}
};
Set a Consent Mode
The Consent Mode will be in charge of sending the right information, depending on what you have configured.
It will be stored in a _pprv
cookie along with other Piano products consent, and will be used on all events until it is modified, or until the cookie is deleted.
Method:
pa.consent.setMode(mode)
Parameters | Type | Description |
---|---|---|
mode | string | Privacy Mode. opt-in , essential or opt-out |
pa.consent.setMode('essential');
If you don't set any Consent Mode (and none stored), the value set for configuration window.pdl.consent.defaultPreset.PA
will be applied by default.
opt-in
by default.
Retrieve the Consent Mode
If you want to know the current mode used by the SDK, you can use the following method:
Method:
pa.consent.getMode()
pa.consent.getMode(); // Return a string with the Consent Mode value
Manage default Consent modes
As explained in the Key notion section, you can manage your default Consent Modes by controlling several items:
- storage
- properties / events
- the value your visitor_privacy_mode and visitor_privacy_consent properties will take
This is achieved by declaring mode items before loading the SDK, thanks to window.pdl.consent_items.PA
object.
You need to define the type of items you need to edit: properties
, events
or storages
.
You'll then need to define the priority level of each property/event/storage you need to modify. Three levels exist: mandatory
(higher priority) > essential
> optional
(lower priority).
Priority level refers to the consent level required for the data to be sent/stored. You can imagine it as follow:
Any item with a higher priority will also be sent with lower priority modes. For example, an item with a "mandatory" priority will be included de facto in "essential" and "opt-in" modes.
On the other hand, if we try to avoid sending event_collection_platform
in "opt-out" and "essential" modes:
window.pdl.consent_items = {
"PA": {
"properties": {
"event_collection_platform": "optional"
}
}
};
As event_collection_platform
has the lowest priority level ("optional"), it won't be included into "essential" and "opt-out" modes.
The window.pdl.consent_items.PA
object specifications:
Property | Description | Type | Value |
---|---|---|---|
properties | Properties priority configuration | object of consentItem | { consentItem } |
events | Events priority configuration | object of consentItem | { consentItem } |
storages | Storages priority configuration | object of consentItem | { consentItem } |
The window.pdl.consent_items.PA.properties
,window.pdl.consent_items.PA.events
, window.pdl.consent_items.PA.storages
(consentItem
) objects specifications:
Property | Description | Type | Value |
---|---|---|---|
<key> | Key to configure, with the priority as the value | string | event_collection_platform |
Complete example:
window.pdl.consent_items = {
"PA": {
"properties": {
"event_collection_platform": "essential",
"event_collection_version": "optional"
},
"events": {
"ad.view": "optional",
"ad.click": "essential"
}
},
};
Manage a custom Consent mode
By default, the custom
mode uses the same rules as the opt-in
mode.
As explained in the Key notion section, you can manage your custom Consent Mode by controlling several items:
- storage
- properties / events
- the value your
visitor_privacy_mode
andvisitor_privacy_consent
properties will take
You first need to declare the "source mode" of your custom mode with window.pdl.consent_modifiers.PA.source
, with one of the default modes:
opt-in
essential
opt-out
Each rule is then a new entry in the window.pdl.consent_modifiers.PA.patches
array, with an action
and an item
.
Example trying to avoid sending event_collection_platform
in "opt-out" and "essential" modes:
window.pdl.consent_modifiers = {
"PA": {
"source": "essential",
"patches": [
{
"action": "exclude",
"item": {
"key": "event_collection_platform",
"type": "property"
},
},
]
},
};
The property
named event_collection_platform
has been excluded from the custom mode.
The window.pdl.consent_modifiers.PA
object specifications:
Property | Description | Type | Value |
---|---|---|---|
source | Base mode for configuration of the custom mode | string | opt-in , essential or opt-out |
patches | Patches to edit configuration of the custom mode | array of modePatch | [ modePatches ] |
The window.pdl.consent_modifiers.PA.patches
(modePatch
) array specifications:
Property | Description | Type | Value |
---|---|---|---|
action | Action to perform | string | exclude or include |
item | Item to perform action on | patchItem | patchItem |
The window.pdl.consent_modifiers.PA.patches[].item
(patchItem
) object specifications:
Property | Description | Type | Value |
---|---|---|---|
key | Key of the item | string | page |
type | Type of the item | string | cookie , event or property |
Complete example:
window.pdl.consent_modifiers = {
"PA": {
"source": "optout",
"patches": [
{
"action": "exclude",
"item": {
"key": "event_collection_platform",
"type": "property"
},
},
{
"action": "exclude",
"item": {
"key": "ad.view",
"type": "event"
},
},
]
},
};
You can also manage the custom mode name (sent in visitor_privacy_mode
) and consent type (sent in visitor_privacy_consent
) with:
Method:
pa.consent.setCustomModeMetadata(modeName, modeConsent)
Parameters | Type | Description |
---|---|---|
modeName | string | Custom Consent mode name |
modeConsent | boolean | Custom Consent mode consent status |
pa.consent.setMode('custom');
pa.consent.setCustomModeMetadata('myCustomMode', false);
Don't forget to set the mode to custom
to apply the changes