Read the choice

Read the choice when your own code must wait for consent: loading a pixel from JavaScript, starting a session recorder or showing personalised content.

Before you start#

The runtime is installed on the page.
Your code runs after the runtime tag, where window.PiedapConsent exists.

Read it in the browser#

Wait for ready. It resolves once the runtime knows which form applies and what this browser already answered.
JavaScript
```
PiedapConsent.ready.then((consent) => {
  console.log(consent.law, consent.consentModel, consent.decided);
});
```

Check a purpose key or a category with hasConsent.

JavaScript

if (PiedapConsent.hasConsent('analytics')) {
  console.log('analytics allowed');
}
PiedapConsent.hasConsent('MARKETING');

Wait for a purpose with whenGranted. It resolves at once if the purpose is already allowed, and otherwise when the visitor allows it.

JavaScript

PiedapConsent.whenGranted('marketing').then(() => {
  const pixel = document.createElement('script');
  pixel.src = 'https://ads.example.com/pixel.js';
  document.head.appendChild(pixel);
});

Listen for change to react when the visitor changes or withdraws the choice. on returns a function that removes the listener.

JavaScript

const off = PiedapConsent.on('change', (consent) => {
  if (!consent.categories.ANALYTICS) {
    window.sessionRecorder?.stop();
  }
});

Reload the page and answer the banner.

Your whenGranted code runs when you allow the purpose, and the change listener runs at every choice. change is sent a second time once the API has stored the choice.

Three things to know:

ready always resolves, also when the API cannot be reached. It never rejects.
Before ready, hasConsent answers from the choice stored in this browser, and false when there is none.
Where no form applies to the visitor's region, every category is allowed and purpose keys are unknown. Check a category there.

What the snapshot holds#

ready, getConsent() and every listener give the same object. This one is shortened:

JSON

{
  "consentId": "cns_3f9a1c0e5b7d4a2c9e8f6b1d0a7c5e42",
  "formKey": "cookie-banner",
  "formVersion": 3,
  "consentModel": "OPT_IN",
  "law": "DPDP",
  "purposes": { "essential": true, "analytics": true, "marketing": false },
  "categories": { "ANALYTICS": true, "MARKETING": false },
  "decided": true
}

Every field and method is in Browser runtime methods. Every event is in Browser runtime events.

Read it from other places#

Code that may run before the runtime

A tag loaded through Tag Manager may run first. Queue a callback, and the runtime calls it once it is ready:

JavaScript

window.piedapConsentQueue = window.piedapConsentQueue || [];
window.piedapConsentQueue.push((consent) => {
  if (consent.hasConsent('analytics')) {
    console.log('analytics allowed');
  }
});

Code that cannot hold a reference to PiedapConsent can listen on window:

JavaScript

window.addEventListener('piedap:consent', (event) => {
  const allowed = event.detail.categories.MARKETING;
  document.body.classList.toggle('ads-allowed', allowed);
});

A bundle that uses the npm package

The object that createConsent() returns has the same methods. Import it where you need it:

JavaScript

import { consent } from './consent.js';

const state = await consent.ready;
console.log(state.purposes);

Your server

The runtime writes the choice to the first-party cookie piedap_consent, so your server can read it on the next request. The server SDKs parse it: see Node.js helpers and Python helpers. The format is in Cookies and browser storage.

A visitor can edit a cookie. Use it to decide what to load. For a decision that must be authoritative, read the record from the API with a secret key.

Before you start#

Read it in the browser#

What the snapshot holds#

Read it from other places#

Related#