Browser runtime events

The browser runtime reports every change in three ways: listeners added with on(), a DOM event on window and a push to window.dataLayer. Each is listed here with when it fires and what it carries.

Requirements#

• Runtime version 1.0.7, loaded with a publishable key.
• For the data layer push: window.dataLayer must be an array.

Install#

Load the runtime with the script tag or the npm package. See Browser runtime options.

Add a listener#

on()#

Adds a listener for one event and returns a function that removes it.

Returns () => void, which removes the listener.

Errors None. An error thrown by a listener is caught and written to the console, and the other listeners still run.

const off = PiedapConsent.on('change', (consent) => {
  console.log('analytics:', consent.purposes.analytics);
});

off();

Events#

Every event passes the consent snapshot to its listener.

ready#

The runtime has finished starting.

• Sent once the runtime knows which form applies and what this browser already answered.
• Sent also when the API cannot be reached, after error.
• A listener added later is called at once.

PiedapConsent.on('ready', (consent) => {
  console.log(consent.decided ? 'answered' : 'not answered yet');
});

change#

A choice was made.

• Sent for a choice from the banner, the preferences, a method on this page or a Global Privacy Control signal.
• Sent a second time when the API has stored the choice. From then on the snapshot carries the consentId.

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

show#

The first layer was shown, by the runtime or by show().

PiedapConsent.on('show', () => document.body.classList.add('banner-open'));

hide#

The banner and dialogs were closed, by a choice or by hide().

PiedapConsent.on('hide', () => document.body.classList.remove('banner-open'));

preferences#

The preferences dialog or the opt-out dialog was opened.

PiedapConsent.on('preferences', (consent) => {
  console.log('preferences opened for', consent.formKey);
});

error#

An API call failed. The choice still applies in this browser.

• Sent when the API cannot be reached at start.
• Sent when the API refuses a write.
• Sent when another language of the form cannot be loaded.

PiedapConsent.on('error', (consent) => {
  console.warn('consent not synced', consent.pendingSync);
});

DOM event#

piedap:consent#

A CustomEvent on window, for code that cannot hold a reference to PiedapConsent.

It is sent when the runtime has resolved the visitor's form, and again at every choice.

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

Data layer push#

piedap_consent_update#

An object pushed to window.dataLayer at the same moments as the DOM event.

{
  event: 'piedap_consent_update',
  piedap_consent: {
    purposes: { essential: true, analytics: true, marketing: false },
    partners: { analytics: { 'google-analytics': true, matomo: false } },
    categories: {
      STRICTLY_NECESSARY: true,
      FUNCTIONAL: false,
      ANALYTICS: true,
      MARKETING: false,
      PERSONALISATION: false,
      SALE_OR_SHARING: false,
      SENSITIVE: false,
    },
    consentModel: 'OPT_IN',
    law: 'DPDP',
    decided: true,
  },
}

The push happens only when window.dataLayer is an array. The runtime creates the array whenever it sends Google Consent Mode signals. If you turned those off, create it before the tag:

<script>window.dataLayer = window.dataLayer || [];</script>

In Tag Manager, trigger on the custom event piedap_consent_update. Read a data layer variable such as piedap_consent.categories.MARKETING. See Tag managers and CMS.