Browser runtime options

The browser runtime takes its options from the script tag, from window.PiedapConsentConfig or from createConsent(). Each option is listed here with its type and default.

Requirements#

• A publishable key, pk_…. See Keys and where to use them.
• For the script tag: a page where the tag can be the first script in <head>.
• For the npm package: Node.js 18 or later to build. The package ships TypeScript types.

Install#

Add the script tag to every page. loader.js always serves the current runtime, version 1.0.7.

<script src="https://console.dpconsent.com/consent/sdk/v1/loader.js"
        data-piedap-key="pk_…"></script>

An application that bundles its own JavaScript installs the package from your deployment instead.

npm install https://console.dpconsent.com/consent/sdk/v1/packages/piedap-consent-1.0.7.tgz

Install on a website explains where the tag goes. The versioned files and their integrity hashes are in Runtime files.

Load the runtime#

Script tag#

The tag starts the runtime and creates window.PiedapConsent.

• Do not add async, defer or type="module".
• The runtime takes the API address from the script's own address.
• Without a key, or with a key that does not start with pk_, nothing starts. The console shows why.
• A second tag on the same page is ignored.

createConsent()#

Starts the runtime from a bundle and returns its controller.

Returns a ConsentController with the browser runtime methods.

Errors Throws Error when publicKey or apiUrl is missing, and when publicKey does not start with pk_.

import { createConsent } from '@piedap/consent';

export const consent = createConsent({
  apiUrl: 'https://console.dpconsent.com/consent',
  publicKey: 'pk_…',
  cookieDomain: '.example.in',
});

const state = await consent.ready;
console.log(state.law, consent.hasConsent('analytics'));

The package is the same runtime without the global. It differs from the script tag in three ways:

• It does not read options from a script tag or from window.PiedapConsentConfig.
• It starts when your bundle runs, so scripts earlier in the page are not held automatically.
• It does not install the IAB stubs early.

Script tag attributes#

A boolean attribute is off when its value is false, 0 or off. It is on when the value is true, 1, on or empty. Any other value keeps the default.

<script src="https://console.dpconsent.com/consent/sdk/v1/loader.js"
        data-piedap-key="pk_…"
        data-piedap-cookie-domain=".example.in"
        data-piedap-allow-hosts="cdn.example.in, pay.example.in"
        data-piedap-metadata='{"storeRegion":"south-india"}'></script>

The floating privacy button also follows the form's Privacy button setting. Where a DPDP region rule applies, the button stays unless the page has its own data-piedap-open element.

Configuration options#

Set window.PiedapConsentConfig before the tag, or pass the same options to createConsent().

<script>
  window.PiedapConsentConfig = {
    cookieDomain: '.example.in',
    blockedHosts: { 'tracker.example.com': 'MARKETING' },
    allowedHosts: ['cdn.example.in'],
    metadata: { storeRegion: 'south-india' },
  };
</script>
<script src="https://console.dpconsent.com/consent/sdk/v1/loader.js"
        data-piedap-key="pk_…"></script>

The IAB stubs are never installed from this object. Use data-piedap-tcf and data-piedap-gpp, or the script URL. Signed-in visitors explains identity, and Identifiers explains identifiers.

Script URL parameters#

Use these when an installer can load a script but cannot set attributes on it.

<script
  src="https://console.dpconsent.com/consent/sdk/v1/loader.js?key=pk_…&amp;locale=hi">
</script>

When one option is set in several places, window.PiedapConsentConfig wins, then the data attribute, then the URL.

Markup attributes#

The runtime reads these attributes on other elements of the page.

<script type="text/plain" data-consent="analytics" data-partner="matomo"
        src="https://matomo.example.in/matomo.js"></script>

<a href="#" data-piedap-open>Privacy settings</a>

Hold tags until consent explains when marked tags are checked and released.

Hosts held by default#

With autoBlock on, a script or frame from one of these hosts waits until its category is allowed.

• A host covers its subdomains. The most specific rule wins.
• The page's own host is never held.
• Payment, fraud-prevention and bot-protection services are not on the list.
• Google's tag hosts are not on the list. They follow Google Consent Mode instead.
• Add hosts with blockedHosts. Exempt hosts with allowedHosts or data-piedap-allow-hosts.