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.

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

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;

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

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.

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

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);

tip

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