Skip to main content

Mark scripts and iframes

Manual preemptive blocking holds scripts and iframes until the visitor gives the required consent. You write the marking in the HTML, and the banner unblocks the element once consent is given.

v2 banner

The v2 banner uses a different marking, with data-managed="as-oil". See Manual marking (v2). If you do not know which banner your site uses, read Which banner your site is using.

Who this is for​

This is for you if you edit the site HTML by hand and add third-party scripts or iframes, such as a widget, a video or a map. The WordPress plugin writes the marking on its own, as explained in the guide Preemptive blocking with the WordPress plugin (in Italian).

Prerequisites​

Before you start, check that:

  • the site loads the banner snippet;
  • the web space has at least one custom vendor with a preemptive blocking URL, and the vendor list is published. This condition turns on the preemptive-block add-on, which unblocks the marked elements. You need it even if the elements are marked by you and not by the WordPress plugin. Without the add-on, the elements stay blocked forever.

Setting the preemptive blocking URL​

  1. In the dashboard, open the List of vendors page of the web space.
  2. Find the custom vendor in the table.
  3. Open the More actions menu on its row.
  4. Choose Edit preemptive blocking URL.
  5. In Enter the URL for the preventative block, write the URL that appears in the src attribute of the vendor's script, then add it with the plus button.
  6. Confirm with Edit.
  7. Publish the list with Save and publish vendor list.

The vendor must be published and visible. IAB vendors, Google catalog vendors and vendors without cookies do not have this option.

The vendor ID

The marking uses the custom vendor ID, for example d116, shown in the ID column of the List of vendors table. A vendor added by hand has an ID that starts with c; a vendor taken from the catalog has an ID that starts with d.

Steps​

External script​

  1. Change the script type to text/avacy-blocked, so the browser does not run it.
  2. Move the address from src to data-avacy-src.
  3. Add data-avacy-requires with the required consent.
<script type="text/avacy-blocked"
data-avacy-src="https://example.com/widget.js"
data-avacy-requires="custom:vendor:d116"></script>

Inline script​

  1. Change the type to text/avacy-blocked.
  2. Add data-avacy-requires. Leave the code inside the tag as it is.
<script type="text/avacy-blocked"
data-avacy-requires="custom:vendor:d116">
console.log('This script runs after consent to d116');
</script>

ES module​

Add data-avacy-type="module". The banner restores that type on unblock.

<script type="text/avacy-blocked"
data-avacy-type="module"
data-avacy-src="https://example.com/widget.mjs"
data-avacy-requires="custom:vendor:d116"></script>

Iframe​

  1. Remove the src attribute.
  2. Write the same address in data-avacy-src.
  3. Add data-avacy-requires.
<iframe data-avacy-src="https://www.youtube.com/embed/VIDEO_ID"
data-avacy-requires="custom:vendor:d116"
width="560" height="315"
title="Video"></iframe>

Replace d116 with your vendor ID. Without consent the iframe stays empty, and the banner does not show any text or buttons in its place.

The banner does not read the value of type: any type the browser does not run works, and text/avacy-blocked is the convention. On unblock, the banner replaces the script with a new node that keeps the other attributes, and gives the iframe back its src, removing the blocking attributes. An element without data-avacy-requires is ignored.

The data-avacy-requires syntax​

data-avacy-requires="custom:vendor:d116;tcf:purpose:1,8,9"

The syntax rules:

  • a requirement has three parts separated by :, in the form framework:axis:id;
  • ; separates one requirement from the next;
  • , separates several ids inside the same requirement;
  • the banner unblocks the element only when all requirements and all ids are granted. With tcf:purpose:1,8,9 you need purposes 1, 8 and 9.
AxisWhat it checksExample
vendorConsent to a vendorcustom:vendor:d116, tcf:vendor:755
purposeConsent to a purpose. With custom it reads custom purposesgcm:purpose:4, tcf:purpose:1, custom:purpose:3
specialFeatureConsent to an IAB special featuretcf:specialFeature:1
legintLegitimate interest on the purpose, which the banner keeps separate from consenttcf:legint:2

The first part, framework, tells the banner which consent system of the web space to read the choice from: custom for custom vendors and purposes, tcf for IAB TCF, gcm for Google Consent Mode. For Google tags see Google tags with gtag.

The banner evaluates each requirement like this:

  1. before the visitor's choice, it unblocks nothing;
  2. if the vendor, purpose or special feature in the requirement, for example d116 in custom:vendor:d116, is not among the visitor's recorded choices, the requirement is not granted;
  3. if the requirement names a framework the web space does not have, the banner uses the custom vendor given in the same marking. Without a custom:vendor:... requirement, the element stays blocked.

With IAB TCF on, only require by hand the purposes and special features that the custom vendor declares, and only as consent. The banner records an IAB purpose only if at least one vendor in the list, IAB or custom, declares it. A requirement on a purpose that no vendor declares, or on legint when the web space does not offer legitimate interest, leaves the element blocked even after Accept cookies.

Execution order​

The banner unblocks elements with these rules:

  • it follows document order;
  • external scripts download in parallel and run in order;
  • an inline script waits for the external scripts before it, for up to 5 seconds each;
  • a new choice re-evaluates the elements still blocked and unblocks what is now granted;
  • the banner does not block again a script that has already run: a withdrawn consent takes effect from the next page load.

Verify​

  1. Open the page in a private window, without giving consent. The script does not run and the iframe has no src attribute.
  2. Choose Accept cookies. The script runs and the iframe gets its src.
  3. Repeat with Reject all. Elements with an actual requirement stay blocked.

For checks in the Network panel and in the dataLayer, see Verify the blocking.

Common problems​

The script never runs, not even after Accept cookies: there is no published custom vendor with a blocking URL, so the add-on stays off (see Prerequisites), or the marking is unreadable (see below).

Unreadable marking: the element stays blocked and, with logs on (window.Avacy.debugModeOn(), see Google tag order and debug mode), the CMP console logs unreadable marking, left blocked among the info-level messages. The most common causes:

  • wrong separator: custom:vendor:d116:tcf:purpose:1 uses : where ; is needed. Write custom:vendor:d116;tcf:purpose:1;
  • unknown axis (gcm:purposes:4) or missing id (gcm:purpose:);
  • framework in uppercase: GCM is not the same as gcm.

Empty attribute: with data-avacy-requires="" the banner unblocks the element at the first valid choice, even with Reject all, because it requires nothing. Write the requirement if the script tracks the visitor.

Site with CSP and nonce: if script-src only accepts scripts with a nonce, put the site nonce on the marked scripts too. The banner unblocks them and keeps their nonce. Without a nonce, the CSP blocks them even after consent. See Scripts with a nonce.

All purposes: the banner has no shorthand for "all purposes". Write them one by one, for example tcf:purpose:1,2,3,4,5,6,7,8,9,10.

Iframe that still has src: it loads immediately. Move the address to data-avacy-src.


Last updated: 27/10/2026.