Hold tags until consent

A tag that sets a tracking cookie must wait for the visitor's answer. Mark the tag up, or let the runtime hold the hosts it knows. Both release a tag the moment its purpose is allowed.

Mark up a tag#

The tag does not load until you allow its purpose. Markup works wherever the runtime tag sits, because browsers never run a text/plain script.

• Purpose keys are case sensitive. A purpose key wins when a category has the same name.
• The categories are FUNCTIONAL, ANALYTICS, MARKETING, PERSONALISATION, SALE_OR_SHARING and SENSITIVE, in any case.
• Where no form applies to the visitor's region, every category is allowed and no purpose keys exist. Mark a tag with its category if it must run there.
• For a module script, keep type="text/plain" and add data-type="module".
• For one partner of a purpose, add data-partner. See Let visitors choose partners.
• A released script loads like an async script. Do not use document.write in a script you hold.

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

Let the runtime hold known hosts#

With the runtime as the first script in <head>, scripts and iframes from hosts on its list are held without markup. This is on by default. A host rule covers its subdomains, and your own host is never held.

The list is in Browser runtime options. It leaves out payment, fraud-prevention and bot-protection services. It also leaves out Google's tag hosts: Google tags load and follow Google Consent Mode.

Automatic blocking does not hold image pixels, fetch calls or stylesheets. Gate those in your own code, as in Read the choice.

To change the list, add hosts with blockedHosts and exempt hosts with allowedHosts. Set them before the runtime tag:

<script>
  window.PiedapConsentConfig = {
    blockedHosts: { 'tracker.example.com': 'MARKETING' },
    allowedHosts: ['intercom.io', 'intercomcdn.com'],
  };
</script>

To turn automatic blocking off, add data-piedap-auto-block="false" to the runtime tag. Marked tags still work.

Placeholders for held frames#

An iframe held by automatic blocking, such as a YouTube embed, is replaced by a placeholder. It says why the content is missing and has one button, Allow and show. The button allows that category, keeps the visitor's other answers and loads the frame.

A frame you mark with data-src waits as an empty frame. Add your own text and button next to it:

<button type="button" id="film-allow">Allow and show the film</button>
<script>
  document.getElementById('film-allow').addEventListener('click', () => {
    PiedapConsent.allowCategory('MARKETING');
  });
</script>

Call allowCategory only for a category your form asks about.

When a visitor withdraws#

When a category stops being allowed, the runtime:

• sends the new state to Google Consent Mode and the other tags it signals
• deletes the first-party cookies known to belong to that category
• holds any new script or frame of that category

It cannot stop a script that already ran, and it cannot delete third-party cookies. Stop your own code in a change listener:

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

Related#

• Read the choice
• Let visitors choose partners
• Browser runtime options
• Banner and tag problems