Skip to main content

Backward compatibility with the v2 banner

This page explains what happens to site code written for the v2 banner (window.AVACY) when the web space moves to the v3 banner (window.Avacy): what keeps working and what you need to rewrite. Each table pairs the v2 row with the v3 row, or says that there is no equivalent.

To migrate the web space

This page does not explain how to migrate. It only covers code written by hand in the site. The steps to migrate from the dashboard, the WordPress plugin, the GTM template or the HTML snippet are in the guide Switching to the new cookie banner (in Italian).

Who this is for​

This page is for you if you added code to the site that depends on the v2 banner, for example a preferences link, a listener, a script marked by hand or CSS on the banner classes.

Prerequisites​

Before you start, check that:

  • you have the list of site code that mentions AVACY, AS_OIL, oil_data, as-oil, avacy_consent, avacy_interaction or avacy_reject_all. The listener on avacy_consent and the two methods AVACY.showPreferenceCenter and AVACY.getPurposeConsents keep working (sections Events and Global object). Check only the differences listed;
  • you know when the web space moves to the v3 banner. Until then the v2 banner stays active and the v2 code keeps working.

Steps​

  1. If the site has the three-tag snippet, replace it with the single tag (Snippet table).
  2. Rewrite every use of AS_OIL, oil_data and the other AVACY methods with the API and Storage tables.
  3. Rewrite the listeners with the Events table. Listeners on avacy_consent stay, and you only need to check them.
  4. Check the scripts marked by hand with the Preemptive blocking table.
  5. Remove the CSS written on the .as-oil classes (section Appearance).
  6. Clear the page cache and the CDN cache, if the site uses them. They can keep the old tags.

Snippet​

The v2 banner uses three tags, the v3 banner a single <script>, the loader. The dashboard shows the snippet in the web space settings.

v2 snippet.

<script id="oil-configuration" type="application/configuration"
data-remote-config="https://<tenant>.avacy-cdn.com/config/<tenant>/<uuid>/banner.json"></script>
<script src="https://<tenant>.avacy-cdn.com/current/dist/oilstub.min.js"></script>
<script src="https://<tenant>.avacy-cdn.com/current/dist/oil.min.js"></script>

v3 snippet.

<script src="https://<tenant>.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=<uuid>"></script>

Replace <tenant> and <uuid> with the values from the dashboard. The loader downloads the web space configuration, bundle and add-ons. The loader includes the Google Consent Mode default and, if TCF is active, the __tcfapi stub, with no separate oilstub file.

If the site already has the single tag, change nothing. The dashboard also gives the single tag to web spaces on v2, and the CDN serves a script that loads oilstub.min.js and oil.min.js. At migration the same URL serves the v3 loader.

After the switch, the old snippet also shows the v3 banner: the v2 banner reads the new configuration and hands over to v3. Replace it with the single tag anyway.

One snippet per page

The old three-tag snippet and the single tag must never be on the same page. When you add the single tag, remove the old snippet. With both, the banner may not appear.

Global object​

v2 bannerv3 banner
window.AVACY (alias of window.AS_OIL and window.PAPYRI)window.Avacy

window.Avacy exists after the loader has loaded. Code that runs early waits for the avacy:ready event (see Events).

On web spaces migrated from v2, the v3 banner also creates window.AVACY, with only two methods: showPreferenceCenter(mode) and getPurposeConsents(). They are created by the legacy-compat add-on, which the dashboard turns on automatically. If the page already has its own window.AVACY, the add-on only adds the missing methods. On a web space created with the v3 banner window.AVACY does not exist: the code uses window.Avacy. AS_OIL and PAPYRI do not exist in any case.

JavaScript API​

v2 bannerv3 bannerNotes
AVACY.showPreferenceCenter('absolute')Avacy.showPreferenceCenter()Opens the panel as an overlay. On migrated web spaces the v2 call still works, and is the same as the v3 one.
AVACY.showPreferenceCenter() or ('inline')Avacy.showPreferenceCenter()The v3 banner has no inline mode: the panel always opens as an overlay. On migrated web spaces AVACY.showPreferenceCenter() always opens the panel as an overlay, even with 'inline': the add-on does not look for #oil-preference-center.
AVACY.showVendors()Avacy.showPreferenceCenter({ section: 'vendor' })Opens the first vendor section, or the first item if the web space has no vendors. The dashboard converts the "show vendors" link in the banner texts. You need to rewrite the one written by hand in the site like this.
AVACY.changeLanguage(lang)Avacy.changeLanguage(lang)Also accepts it-IT, en_US or EN. See Banner language.
AVACY.reload()No equivalent
AVACY.verboseModeOn() and verboseModeOff()Avacy.debugModeOn() and debugModeOff()The flag moves from the oil_verbose cookie to localStorage (avacy:debug), and the v3 banner reloads the page.
AVACY.getPurposeConsents()Still works on migrated web spaces. Elsewhere Avacy.getConsent()On migrated web spaces it returns a Promise with TCF purposes 1 to 11, each true or false.
AVACY.hasConsents(), getCustomVendors()Avacy.getConsent()Returns the purposes, specialFeatures and vendors maps.
AVACY.triggerOptIn(), AVACY.triggerOptOut()No equivalent
AVACY.previewModeOn() and previewModeOff()No equivalent
AVACY.eventCollection and AVACY.isInCollection()No equivalentThe v3 banner keeps no history. Read the state with Avacy.getConsent().
AVACY.readLocalstorage(), clearVendorlistCaches() and the other internal methodsNo equivalent

Events​

The v3 banner emits CustomEvents on the document with the avacy: prefix. The v2 banner emitted events on the window and postMessage messages. The v3 banner still emits avacy_consent on the window, and a v2 listener on that event keeps working. It does not emit the other v2 events, so you need to rewrite those listeners.

v2 bannerv3 bannerNotes
window → avacy_consent with detail.trigger === 'consent_update' or 'page_load'window → avacy_consent, with the same trigger valuesNo need to rewrite it. The listener keeps working, with the differences below. detail.gcm is still an array of the granted types.
window → avacy_consent with detail.trigger === 'consent_update'document → avacy:consent-savedNative v3 banner alternative. The detail has type, timestamp and gcm. Read purposes and vendors with Avacy.getConsent().
window → avacy_consent with detail.trigger === 'page_load'document → avacy:consent-loadedNative v3 banner alternative, emitted at every startup. With no saved consent the detail is { valid: false }.
avacy_consent → detail.gcm (array of granted types)avacy:consent-saved → detail.gcmOnly for the native alternative. It is an object with the seven Consent Mode types, each 'granted' or 'denied'. It is undefined without Google Consent Mode.
dataLayer → { event: 'avacy_consent_update' }dataLayer → { event: 'avacy_consent_update' }No need to rewrite it: it fires at the same moments as in v2, after every save (rejection included) and on load with a saved consent. It does not fire on the first visit.
window → avacy_interactionNo equivalentavacy:consent-saved gives the consent type (detail.type), not the button pressed.
window → avacy_reject_allNo equivalentThe v2 banner emitted it with Reject all and when the banner was closed with the X. In the v3 banner both save a RejectAll: use avacy:consent-saved with detail.type.
postMessage oil_showndocument → avacy:banner-shown
postMessage oil_click_advanced_settingsdocument → avacy:cpc-opened
postMessage oil-checked-optinNo direct equivalentThe v3 banner emits avacy:ready at the end of startup. Read the state with Avacy.getConsent().
postMessage oil_optin_done, oil_soi_optin_done, oil_optout_doneavacy:consent-savedTell the cases apart with detail.type (AcceptAll, RejectAll, Personalized).
postMessage oil_close_banner_button_clicked, oil_optin_done_button_clicked, oil_as_cpc_privacy_selectedNo equivalentThe v3 banner does not emit an event per click. Closing the banner without a choice saves a RejectAll, so avacy:consent-saved arrives.

Listener for the v3 banner.

<script>
document.addEventListener('avacy:consent-saved', function (event) {
console.log('Consent saved:', event.detail.type);
});
</script>

The event fires with page_load when there is a saved consent and with consent_update at every choice. Compared with v2, these fields and the first visit change.

Field or casev2 bannerv3 banner
customVendorsWithConsentCounted only the purposes, and ignored the consent to the vendorThe vendor is included with the consent to the vendor and to all the purposes it declares
iabVendorsWithConsentThe vendor was included only with all purposes acceptedThe consent to the vendor is enough
optintrue in every saved consent, even after Reject allfalse after a full rejection: Reject all, the X, Continue without accepting or preferences saved with everything off
First visit, no choicepage_load with optin: false and empty listsNo event until the first choice

For the fields and the vendor rule, see Banner events.

Preemptive blocking​

In the v3 banner, preemptive blocking is handled by the preemptive-block add-on. The dashboard turns it on when the web space has vendors with preemptive blocking URLs. Without those vendors the add-on is missing and the scripts marked by hand stay blocked. Set the preemptive blocking URL on at least one vendor, as explained in the guide Preemptive blocking (in Italian).

With the add-on active, the v2 marking (data-managed="as-oil") keeps working, because the add-on translates the attributes by name.

v2 attributes present but empty

In the v2 banner data-purposes="", data-legints="" and data-special-features="" mean "all ids". The v3 banner has no "all" form: these empty attributes leave the script blocked. The console reports it with a warning. List the ids.

Empty data-iab-vendor="" and data-custom-vendor="", on the other hand, require nothing, as in v2.

Sites with WP plugin 1.3.1

Plugin 1.3.1 writes data-purposes="Array,Array,…" together with a data-custom-vendor. The v3 banner recognizes this exact fingerprint and ignores data-purposes: the script is unblocked by the consent to the vendor alone, even with TCF on. A visitor who accepts the vendor but rejects its IAB purposes still runs the script. Update the plugin to the latest version to get the correct marking. Markings written by hand with values other than numbers stay blocked.

v3 banner format for new markings.

v2 bannerv3 banner
type="as-oil"type="text/avacy-blocked"
data-managed="as-oil"data-avacy-requires="…"
data-src="…"data-avacy-src="…"
data-type="text/javascript"data-avacy-type="…" (optional)
data-custom-vendor="d116"custom:vendor:d116
data-iab-vendor="755"tcf:vendor:755
data-purposes="1,2,4"tcf:purpose:1,2,4
data-legints="2"tcf:legint:2
data-special-features="1"tcf:specialFeature:1

Join multiple requirements with ; in the same attribute. The v3 banner reads them as AND.

<!-- v2 banner -->
<script data-managed="as-oil" data-type="text/javascript" data-src="path/to/the/script.js"
data-purposes="1,2,4" data-custom-vendor="d116" type="as-oil"></script>

<!-- v3 banner -->
<script type="text/avacy-blocked" data-avacy-src="path/to/the/script.js"
data-avacy-requires="custom:vendor:d116;tcf:purpose:1,2,4"></script>

For the v3 marking, see Mark scripts.

Storage​

v2 bannerv3 banner
Consent cookie nameoil_dataavacy_consent
SameSite attributeNone (with Secure, on https)Lax
Durationcookie_expires_in_daysThe duration set in the dashboard, the same as in v2 (usually 183 days)

The v3 banner does not read oil_data, so visitors who had already chosen see the banner again on their first visit after the switch. Rewrite the scripts that read oil_data with Avacy.getConsent(), because the content of avacy_consent is an internal format and can change.

The SameSite change from None to Lax changes how the cookie behaves when the site is in an iframe on another domain.

The v3 banner lives in a Shadow DOM, which the CSS rules on the v2 banner's .as-oil classes do not reach.

v2 bannerv3 banner
CSS rules on the .as-oil classesNo CSS customization supported
Google Fonts loaded by the bannerThe banner does not load external fonts

The v2 banner loaded a Google Font with automatic loading. The v3 banner uses Arial by default, and the site font works only if the site already loads it.

You set the appearance, colors and font of the v3 banner from the dashboard. The instructions are in the guide Cookie banner (in Italian).

Power Opt-In​

The v3 banner has no Power Opt-In, so each site asks for consent on its own. The dashboard turned on Power Opt-In automatically on web spaces with multiple domains.

TCF activation conditions​

The v3 banner activates TCF only if the web space meets one of these conditions:

  • at least one published IAB vendor;
  • at least one published Google partner;
  • a custom vendor that declares IAB purposes or special features.

In the other cases the v3 banner does not generate the TC String and does not offer the __tcfapi API.

The v2 banner always offered __tcfapi and generated the TC String, even without IAB vendors. After migration, on a site without these conditions __tcfapi no longer exists: a third-party script that calls it does not find it.

If a site script calls __tcfapi, publish the IAB vendors it uses first. After the switch, typeof __tcfapi in the console must return function.

Verify​

  1. Open the site in a private window and open the browser console.
  2. Type typeof Avacy. The console must return object.
  3. Type typeof AVACY. On a web space migrated from v2 the console returns object, because of the legacy-compat add-on. On a web space created with the v3 banner it returns undefined.
  4. Add the listener from the Events section to the page.
  5. Press Reject all on the banner, or close it with the X if the button is missing. The listener must write RejectAll to the console.
  6. Reload the page. The banner must not appear again.

Common problems​

The most frequent issues:

  • The banner does not appear and the page has two snippets: the old three-tag snippet and the single tag are on the same page. Remove the old snippet;
  • The listener on avacy_consent does not fire: the v3 banner emits avacy_consent on the window, so the listener must be on the window. On the first visit, before the choice, the v3 banner emits nothing. The listener fires after the first choice;
  • The listener on avacy_consent receives vendor lists that differ from v2: see Differences in avacy_consent;
  • The listener on avacy_interaction or avacy_reject_all no longer fires: the v3 banner does not emit these two events. Use avacy:consent-saved;
  • AVACY is undefined on a web space created with the v3 banner: window.AVACY exists only on migrated web spaces. Use window.Avacy;
  • Avacy is undefined in a page script: the script runs before the loader. Wait for avacy:ready;
  • A script marked by hand stays blocked: check that the web space has vendors with preemptive blocking URLs and that the marking does not have empty data-purposes, data-legints or data-special-features;
  • The visitor sees the banner again after migration: the v3 banner does not read the oil_data cookie.

Last updated: 10/11/2026.