Skip to main content

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.

"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.

info

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 and visitor_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 Mode"_pcid" cookieVisitor IDvisitor_privacy_modevisitor_privacy_consentProperties / eventsExclusion / AnonymizationComment
opt-inoptintrueall
essentialexemptfalsesomeRequires a specific configuration as explained in our Privacy center
opt-outoptoutfalsesomeAll events will be excluded and anonymized. More information in our Privacy Center
customyou decideyou decideyou decideyou decideyou decide (same base as essential mode)Some cookies, properties and events are included by default to a custom mode
tip

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;

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'
}
};

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)

ParametersTypeDescription
modestringPrivacy Mode. opt-in, essential or opt-out
pa.consent.setMode('essential');
note

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.

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

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:

Consent priorities

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:

PropertyDescriptionTypeValue
propertiesProperties priority configurationobject of consentItem{ consentItem }
eventsEvents priority configurationobject of consentItem{ consentItem }
storagesStorages priority configurationobject 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:

PropertyDescriptionTypeValue
<key>Key to configure, with the priority as the valuestringevent_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"
}
},
};

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 and visitor_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:

PropertyDescriptionTypeValue
sourceBase mode for configuration of the custom modestringopt-in, essential or opt-out
patchesPatches to edit configuration of the custom modearray of modePatch[ modePatches ]

The window.pdl.consent_modifiers.PA.patches (modePatch) array specifications:

PropertyDescriptionTypeValue
actionAction to performstringexclude or include
itemItem to perform action onpatchItempatchItem

The window.pdl.consent_modifiers.PA.patches[].item (patchItem) object specifications:

PropertyDescriptionTypeValue
keyKey of the itemstringpage
typeType of the itemstringcookie, 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)

ParametersTypeDescription
modeNamestringCustom Consent mode name
modeConsentbooleanCustom Consent mode consent status
pa.consent.setMode('custom');
pa.consent.setCustomModeMetadata('myCustomMode', false);
tip

Don't forget to set the mode to custom to apply the changes