Skip to main content

Consent management

Prerequisite

Consent Management is only available on JS ≥ 6.8.0, Android ≥ 3.4.0 and iOS ≥ 3.1.0.

If you use PA JS < 6.8.0 / Android < 3.4.0 / iOS < 3.1.0, please use legacy Privacy management methods.

note

If you want to use the ePrivacy exemption, please read this documentation first. Contact our support centre to request an activation process for the ePrivacy exemption.

"Consent Management" is the first building block of unified tagging methods across all Piano products.

You will be able to control the data collected, according to the different regulations 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.

All the logic is explained in our Privacy center.

Read first

As a unified way to manage Privacy, “Consent Management” can be triggered from several Piano SDK.

You have two options:

  • You use several Piano Products

    • You can manage consent for all products using the Piano Analytics SDK and this documentation.
    • Or you can use the Composer SDK with this configuration.

    Make sure that only one SDK triggers Privacy instructions.

  • You only use Piano Analytics

    • Use this page to setup you Privacy instructions.

Key notion

A "Consent Mode" is a state in which you can have control over various items:

  • 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 ModesetMode value"_pcid" cookieVisitor IDvisitor_privacy_modevisitor_privacy_consentProperties / eventsExclusion / AnonymizationComment
Opt-inopt-inoptintrueall
ExemptessentialexemptfalsesomeRequires a specific configuration as explained in our Privacy center
Opt-outopt-outoptoutfalsesomeAll events will be excluded and anonymized. More information in our Privacy Center
Extended Opt-out ≥ 6.13.0opt-outextended-optoutfalseallenableExtendedOptout SDK configuration needed. All events will be anonymized thanks to the "Contains personal data" flags. More information in our Privacy Center
Customcustomyou 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.

For JS SDK, you can check which storage keys (cookies), properties and events are included by default in the dedicated article.

For Android SDK, the default configuration is the same as the Privacy modes. Please note that only Optin, Exempt and Optout are available for Consent feature.

You can also find the list of our cookies and storage keys in the Cookies & storage article.

Extended opt-out

Since PA JS 6.13.0, you can turn on "Extended opt-out". This feature anonymously collect exhaustive data for opted-out visitors. See how it works in our Privacy center.

To enable it, you should set the SDK configuration enableExtendedOptout to true.

This will change the behavior of opted-out visitors, who will now send every events and properties, with an anonymized visitor ID (idclient).

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 'v2':

window.pdl = window.pdl || {};
window.pdl.requireConsent = "v2";
window.pdl.consent = {};
// If you use Analytics only
window.pdl.consent.products = ["PA"];

Purposes and products

Since consent v2 (PA JS 6.14.0), the consent is set by purpose instead of Piano products. Each product belongs to one purpose by default, by you can alter our default setup.

Default distribution:

PurposeProducts
Audience measurement (AM)Analytics (PA)
Content personalization and Performance (CP)Composer (COMPOSER)
Advertising (AD)DMP, Social Flow (SOCIAL_FLOW)
Personal Relationship (PR)ID, VX, ESP
Data Layer (DL) (JS only)DL
note

"Data Layer" purpose and the assigned DL product are reserved by Piano. Only the DL product can be assigned to the DL purpose.

Altering the Default Purposes

You can specify your own purposes if the ones provided by Piano don't match your consent banner. For example:

window.pdl = window.pdl || {};
window.pdl.requireConsent = "v2";
window.pdl.consent = {};
window.pdl.consent.defaultPurposes = {
DMP: "Custom purpose 1",
COMPOSER: "Custom purpose 2",
};

In this example since Composer is moved to a different purpose the CP purpose doesn’t contain any product and doesn’t exist anymore.

Based on the above code, here is how the purposes and products would look like after if it's applied:

PurposeProducts
Audience measurement (AM)Analytics (PA)
Custom purpose 2Composer (COMPOSER)
Custom purpose 1DMP
Advertising (AD)Social Flow (SOCIAL_FLOW)
Personal Relationship (PR)ID, VX, ESP
Data Layer (DL)DL

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.setByPurpose(purpose, mode, product?)

ParametersTypeDescription
purposestringPurpose to set. AM, CP, AD, PR or DL
modestringConsent mode. opt-in, essential or opt-out
productstring / arrayProduct(s) to assign to the purpose. PA, COMPOSER, DMP, VX, ID, ESP
pa.consent.setByPurpose("AM", "essential");

// edit AM products
pa.consent.setByPurpose("AM", "essential", ["PA", "COMPOSER"]);

You can also set a Consent mode for all purposes.

pa.consent.setAllPurposes(mode)

ParametersTypeDescription
modestringConsent mode. opt-in, essential or opt-out
pa.consent.setAllPurposes("essential");

If you want to know the current consent mode for each purposes, you can use the following method:

Method:

pa.consent.getByPurpose()

pa.consent.getByPurpose();

// {
// AM: {mode: 'opt-in', products: ["PA"]},
// CP: {mode: 'opt-in', products: ["COMPOSER"]},
// AD: {mode: 'opt-in', products: ["DMP", "SOCIAL_FLOW"]},
// PR: {mode: 'opt-out', products: ["ID", "VX", "ESP"]}
// DL: {mode: 'opt-in', products: ["DL"]},
// }

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 = "v2";
window.pdl.consent = {
defaultPreset: {
PA: "essential",
},
};
// If you use Analytics only
window.pdl.consent.products = ["PA"];

As explained in the Key notion section, you can manage your default Consent Modes by controlling several items:

  • properties / events
  • the value your visitor_privacy_mode and visitor_privacy_consent properties will take

For JS SDK, 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 or events.

You'll then need to define the priority level of each property/event 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 }

The window.pdl.consent_items.PA.properties,window.pdl.consent_items.PA.events (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",
},
},
};

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

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:

  • 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 itemstringevent 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(modeConsent, modeName)

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

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

How to migrate

In order to migrate from Privacy implementation, here are some steps to follow or check:

  • Add initialization for consents

    val pianoConsents = PianoConsents.init(
    applicationContext,
    ConsentConfiguration(
    requireConsent = true,
    defaultPurposes = mapOf(...) // if needed
    )
    )
  • Add consents to Piano Analytics initialization

    PianoAnalytics.init(applicationContext, configuration, pianoConsents)
  • Set default preset (if needed)

    pianoConsents.set(...)
  • Configure privacy modes (if needed)

    PrivacyMode.EXEMPT.allowedEventNames.add("event-name-here")
  • Configure custom privacy mode (if needed)

    PrivacyMode.CUSTOM.apply { ... }
  • Remove all usages of PianoAnalytics.getInstance().privacyModesStorage.allModes

  • Replace setting PianoAnalytics.getInstance().privacyModesStorage.currentMode via pianoConsents.set(...), use this mapping:

    PrivacyMode.OPTIN -> ConsentMode.OPT_IN
    PrivacyMode.EXEMPT -> ConsentMode.ESSENTIAL
    PrivacyMode.OPTOUT -> ConsentMode.OPT_OUT
    PrivacyMode.CUSTOM -> ConsentMode.CUSTOM

    Note: default value "consent not acquired" will be used if you haven't set any other value

  • Purpose values are (JS name in brackets):

    Purpose.AUDIENCE_MEASUREMENT (AM)
    Purpose.CONTENT_PERSONALISATION (CP)
    Purpose.ADVERTISING (AD)
    Purpose.PERSONAL_RELATIONSHIP (PR)