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.
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_interactionoravacy_reject_all. The listener onavacy_consentand the two methodsAVACY.showPreferenceCenterandAVACY.getPurposeConsentskeep 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
- If the site has the three-tag snippet, replace it with the single tag (Snippet table).
- Rewrite every use of
AS_OIL,oil_dataand the otherAVACYmethods with the API and Storage tables. - Rewrite the listeners with the Events table. Listeners on
avacy_consentstay, and you only need to check them. - Check the scripts marked by hand with the Preemptive blocking table.
- Remove the CSS written on the
.as-oilclasses (section Appearance). - 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.
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 banner | v3 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 banner | v3 banner | Notes |
|---|---|---|
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 equivalent | The v3 banner keeps no history. Read the state with Avacy.getConsent(). |
AVACY.readLocalstorage(), clearVendorlistCaches() and the other internal methods | No 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 banner | v3 banner | Notes |
|---|---|---|
window → avacy_consent with detail.trigger === 'consent_update' or 'page_load' | window → avacy_consent, with the same trigger values | No 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-saved | Native 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-loaded | Native 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.gcm | Only 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_interaction | No equivalent | avacy:consent-saved gives the consent type (detail.type), not the button pressed. |
window → avacy_reject_all | No equivalent | The 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_shown | document → avacy:banner-shown | |
postMessage oil_click_advanced_settings | document → avacy:cpc-opened | |
postMessage oil-checked-optin | No direct equivalent | The 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_done | avacy:consent-saved | Tell the cases apart with detail.type (AcceptAll, RejectAll, Personalized). |
postMessage oil_close_banner_button_clicked, oil_optin_done_button_clicked, oil_as_cpc_privacy_selected | No equivalent | The 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>
Differences in avacy_consent
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 case | v2 banner | v3 banner |
|---|---|---|
customVendorsWithConsent | Counted only the purposes, and ignored the consent to the vendor | The vendor is included with the consent to the vendor and to all the purposes it declares |
iabVendorsWithConsent | The vendor was included only with all purposes accepted | The consent to the vendor is enough |
optin | true in every saved consent, even after Reject all | false after a full rejection: Reject all, the X, Continue without accepting or preferences saved with everything off |
| First visit, no choice | page_load with optin: false and empty lists | No 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.
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.
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 banner | v3 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 banner | v3 banner | |
|---|---|---|
| Consent cookie name | oil_data | avacy_consent |
| SameSite attribute | None (with Secure, on https) | Lax |
| Duration | cookie_expires_in_days | The 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.
Banner appearance
The v3 banner lives in a Shadow DOM, which the CSS rules on the v2 banner's .as-oil classes do not reach.
| v2 banner | v3 banner |
|---|---|
CSS rules on the .as-oil classes | No CSS customization supported |
| Google Fonts loaded by the banner | The 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
- Open the site in a private window and open the browser console.
- Type
typeof Avacy. The console must returnobject. - Type
typeof AVACY. On a web space migrated from v2 the console returnsobject, because of thelegacy-compatadd-on. On a web space created with the v3 banner it returnsundefined. - Add the listener from the Events section to the page.
- Press Reject all on the banner, or close it with the X if the button is missing. The listener must write
RejectAllto the console. - 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_consentdoes not fire: the v3 banner emitsavacy_consenton thewindow, so the listener must be on thewindow. On the first visit, before the choice, the v3 banner emits nothing. The listener fires after the first choice; - The listener on
avacy_consentreceives vendor lists that differ from v2: see Differences inavacy_consent; - The listener on
avacy_interactionoravacy_reject_allno longer fires: the v3 banner does not emit these two events. Useavacy:consent-saved; AVACYisundefinedon a web space created with the v3 banner:window.AVACYexists only on migrated web spaces. Usewindow.Avacy;Avacyisundefinedin a page script: the script runs before the loader. Wait foravacy: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-legintsordata-special-features; - The visitor sees the banner again after migration: the v3 banner does not read the
oil_datacookie.
Last updated: 10/11/2026.