Retrocompatibilità con il banner v2
Questa pagina spiega cosa succede al codice del sito scritto per il banner v2 (window.AVACY) quando lo spazio web passa al banner v3 (window.Avacy): cosa continua a funzionare e cosa va riscritto. Ogni tabella abbina la riga v2 alla riga v3, o dice che l'equivalente manca.
Questa pagina non spiega come migrare e riguarda solo il codice scritto a mano nel sito. Gli step da seguire per migrare dalla dashboard, dal plugin WordPress, dal template GTM o dallo snippet HTML sono nella guida Passare al nuovo cookie banner.
A chi serve
Serve a chi ha aggiunto al sito codice che dipende dal banner v2, per esempio un link alle preferenze, un listener, uno script marcato a mano o un CSS sulle classi del banner.
Prerequisiti
Prima di cominciare controlla che:
- tu abbia l'elenco del codice del sito che nomina
AVACY,AS_OIL,oil_data,as-oil,avacy_consent,avacy_interactionoavacy_reject_all. Il listener suavacy_consente i due metodiAVACY.showPreferenceCentereAVACY.getPurposeConsentscontinuano a funzionare (sezioni Eventi e Oggetto globale). Controlla solo le differenze indicate; - tu sappia quando lo spazio web passa al banner v3. Fino ad allora il banner v2 resta attivo e il codice v2 continua a funzionare.
Step
- Se il sito ha lo snippet a tre tag, sostituiscilo con il tag unico (tabella Snippet).
- Riscrivi ogni uso di
AS_OIL,oil_datae degli altri metodi diAVACYcon le tabelle API e Storage. - Riscrivi i listener con la tabella Eventi. I listener su
avacy_consentrestano, e vanno solo controllati. - Controlla gli script marcati a mano con la tabella Blocco preventivo.
- Togli il CSS scritto sulle classi
.as-oil(sezione Aspetto). - Svuota la cache di pagina e del CDN, se il sito le usa. Possono conservare i vecchi tag.
Snippet
Il banner v2 usa tre tag, il banner v3 un solo <script>, il loader. La dashboard mostra lo snippet nelle impostazioni dello spazio web.
Snippet v2.
<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>
Snippet v3.
<script src="https://<tenant>.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=<uuid>"></script>
Sostituisci <tenant> e <uuid> con i valori della dashboard. Il loader scarica configurazione, bundle e add-on dello spazio web. Il loader include il default di Google Consent Mode e, se il TCF è attivo, lo stub __tcfapi, senza file oilstub separato.
Se il sito ha già il tag unico, non cambiare niente. La dashboard dà il tag unico anche agli spazi web su v2, e la CDN serve uno script che carica oilstub.min.js e oil.min.js. Alla migrazione lo stesso URL serve il loader v3.
Anche il vecchio snippet, dopo il passaggio, mostra il banner v3: il banner v2 legge la configurazione nuova e lascia il posto al v3. Sostituiscilo comunque con il tag unico.
Il vecchio snippet a tre tag e il tag unico non devono mai stare nella stessa pagina. Quando metti il tag unico, togli il vecchio snippet. Con tutti e due il banner può non comparire.
Oggetto globale
| Banner v2 | Banner v3 |
|---|---|
window.AVACY (alias di window.AS_OIL e window.PAPYRI) | window.Avacy |
window.Avacy esiste dopo il caricamento del loader. Il codice che parte presto aspetta l'evento avacy:ready (vedi Eventi).
Sugli spazi web migrati da v2 il banner v3 crea anche window.AVACY, con due soli metodi: showPreferenceCenter(mode) e getPurposeConsents(). Li crea l'add-on legacy-compat, che la dashboard accende da sola. Se la pagina ha già un suo window.AVACY, l'add-on aggiunge solo i metodi che mancano. Su uno spazio web creato con il banner v3 window.AVACY non esiste: il codice usa window.Avacy. AS_OIL e PAPYRI non esistono in nessun caso.
API JavaScript
| Banner v2 | Banner v3 | Note |
|---|---|---|
AVACY.showPreferenceCenter('absolute') | Avacy.showPreferenceCenter() | Apre il pannello in sovrimpressione. Sugli spazi web migrati la chiamata v2 funziona ancora, ed equivale alla v3. |
AVACY.showPreferenceCenter() o ('inline') | Avacy.showPreferenceCenter() | Il banner v3 non ha la modalità inline: il pannello si apre sempre in sovrimpressione. Sugli spazi web migrati AVACY.showPreferenceCenter() apre sempre il pannello in sovrimpressione, anche con 'inline': l'add-on non cerca #oil-preference-center. |
AVACY.showVendors() | Avacy.showPreferenceCenter({ section: 'vendor' }) | Apre la prima sezione dei fornitori, o la prima voce se lo spazio web non ha fornitori. La dashboard converte il link "mostra fornitori" nei testi del banner. Quello scritto a mano nel sito va riscritto così. |
AVACY.changeLanguage(lang) | Avacy.changeLanguage(lang) | Accetta anche it-IT, en_US o EN. Vedi Lingua del banner. |
AVACY.reload() | Nessun equivalente | |
AVACY.verboseModeOn() e verboseModeOff() | Avacy.debugModeOn() e debugModeOff() | Il flag passa dal cookie oil_verbose a localStorage (avacy:debug), e il banner v3 ricarica la pagina. |
AVACY.getPurposeConsents() | Sugli spazi web migrati funziona ancora. Altrove Avacy.getConsent() | Sugli spazi web migrati risponde con una Promise sulle finalità TCF da 1 a 11, ciascuna true o false. |
AVACY.hasConsents(), getCustomVendors() | Avacy.getConsent() | Restituisce le mappe purposes, specialFeatures e vendors. |
AVACY.triggerOptIn(), AVACY.triggerOptOut() | Nessun equivalente | |
AVACY.previewModeOn() e previewModeOff() | Nessun equivalente | |
AVACY.eventCollection e AVACY.isInCollection() | Nessun equivalente | Il banner v3 non tiene uno storico. Lo stato si legge con Avacy.getConsent(). |
AVACY.readLocalstorage(), clearVendorlistCaches() e gli altri metodi interni | Nessun equivalente |
Eventi
Il banner v3 emette CustomEvent sul document con prefisso avacy:. Il banner v2 emetteva eventi sul window e messaggi postMessage. Il banner v3 emette ancora avacy_consent sul window, e un listener v2 su quell'evento continua a funzionare. Non emette gli altri eventi v2, quindi quei listener vanno riscritti.
| Banner v2 | Banner v3 | Note |
|---|---|---|
window → avacy_consent con detail.trigger === 'consent_update' o 'page_load' | window → avacy_consent, con gli stessi trigger | Non serve riscriverlo. Il listener continua a funzionare, con le differenze sotto. detail.gcm resta un array dei tipi concessi. |
window → avacy_consent con detail.trigger === 'consent_update' | document → avacy:consent-saved | Alternativa nativa del banner v3. Il detail ha type, timestamp e gcm. Finalità e fornitori si leggono con Avacy.getConsent(). |
window → avacy_consent con detail.trigger === 'page_load' | document → avacy:consent-loaded | Alternativa nativa del banner v3, emessa a ogni avvio. Senza consenso salvato il detail è { valid: false }. |
avacy_consent → detail.gcm (array dei tipi concessi) | avacy:consent-saved → detail.gcm | Solo per l'alternativa nativa. È un oggetto con i sette tipi di Consent Mode, ognuno 'granted' o 'denied'. Vale undefined senza Google Consent Mode. |
dataLayer → { event: 'avacy_consent_update' } | dataLayer → { event: 'avacy_consent_update' } | Non serve riscriverlo: parte negli stessi momenti del v2, dopo ogni salvataggio (rifiuto compreso) e al caricamento con un consenso salvato. Alla prima visita non parte. |
window → avacy_interaction | Nessun equivalente | avacy:consent-saved dà il tipo di consenso (detail.type), non il pulsante premuto. |
window → avacy_reject_all | Nessun equivalente | Il banner v2 lo emetteva con Rifiuta tutto e alla chiusura del banner con la X. Nel banner v3 tutti e due salvano un RejectAll: usa avacy:consent-saved con detail.type. |
postMessage oil_shown | document → avacy:banner-shown | |
postMessage oil_click_advanced_settings | document → avacy:cpc-opened | |
postMessage oil-checked-optin | Nessun equivalente diretto | Il banner v3 emette avacy:ready a fine avvio. Lo stato si legge con Avacy.getConsent(). |
postMessage oil_optin_done, oil_soi_optin_done, oil_optout_done | avacy:consent-saved | Distingui i casi con detail.type (AcceptAll, RejectAll, Personalized). |
postMessage oil_close_banner_button_clicked, oil_optin_done_button_clicked, oil_as_cpc_privacy_selected | Nessun equivalente | Il banner v3 non emette un evento per click. Chiudere il banner senza scelta salva un RejectAll, quindi arriva avacy:consent-saved. |
Listener per il banner v3.
<script>
document.addEventListener('avacy:consent-saved', function (event) {
console.log('Consenso salvato:', event.detail.type);
});
</script>
Differenze di avacy_consent
L'evento parte con page_load quando c'è un consenso salvato e con consent_update a ogni scelta. Rispetto al v2 cambiano questi campi e la prima visita.
| Campo o caso | Banner v2 | Banner v3 |
|---|---|---|
customVendorsWithConsent | Contava solo le finalità, e ignorava il consenso al fornitore | Il fornitore entra con il consenso al fornitore e a tutte le finalità che dichiara |
iabVendorsWithConsent | Il fornitore entrava solo con tutte le finalità accettate | Basta il consenso al fornitore |
optin | true in ogni consenso salvato, anche dopo Rifiuta tutto | false dopo un rifiuto totale: Rifiuta tutto, la X, Continua senza accettare o preferenze salvate con tutto spento |
| Prima visita, senza scelta | page_load con optin: false e liste vuote | Nessun evento fino alla prima scelta |
Per i campi e la regola dei fornitori vedi Eventi del banner.
Blocco preventivo
Nel banner v3 il blocco preventivo spetta all'add-on preemptive-block. La dashboard lo accende quando lo spazio web ha fornitori con URL di blocco preventivo. Senza quei fornitori l'add-on manca e gli script marcati a mano restano bloccati. Imposta l'URL di blocco preventivo su almeno un fornitore, come spiega la guida Blocco preventivo.
Con l'add-on attivo la marcatura v2 (data-managed="as-oil") continua a funzionare, perché l'add-on traduce gli attributi per nome.
Nel banner v2 data-purposes="", data-legints="" e data-special-features="" significano "tutti gli id". Il banner v3 non ha la forma "tutti": questi attributi vuoti lasciano lo script bloccato. La console lo segnala con un avviso. Elenca gli id.
data-iab-vendor="" e data-custom-vendor="" vuoti invece non richiedono niente, come nel v2.
Il plugin 1.3.1 scrive data-purposes="Array,Array,…" insieme a un data-custom-vendor. Il banner v3 riconosce questa impronta esatta e ignora data-purposes: lo script si sblocca con il solo consenso al fornitore, anche con il TCF acceso. Chi accetta il fornitore ma rifiuta le sue finalità IAB fa partire lo script lo stesso. Aggiorna il plugin all'ultima versione per avere la marcatura corretta. Le marcature scritte a mano con valori diversi da numeri restano bloccate.
Formato del banner v3 per le marcature nuove.
| Banner v2 | Banner v3 |
|---|---|
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="…" (facoltativo) |
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 |
Più requisiti si uniscono con ; nello stesso attributo. Il banner v3 li legge in AND.
<!-- banner v2 -->
<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>
<!-- banner v3 -->
<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>
Per la marcatura v3 vedi Marcare gli script.
Storage
| Banner v2 | Banner v3 | |
|---|---|---|
| Nome del cookie del consenso | oil_data | avacy_consent |
| Attributo SameSite | None (con Secure, su https) | Lax |
| Durata | cookie_expires_in_days | La durata impostata nella dashboard, uguale a quella del v2 (di solito 183 giorni) |
Il banner v3 non legge oil_data, quindi chi aveva già scelto rivede il banner alla prima visita dopo il passaggio. Riscrivi gli script che leggevano oil_data con Avacy.getConsent(), perché il contenuto di avacy_consent è un formato interno e può cambiare.
Il cambio di SameSite da None a Lax modifica il comportamento del cookie quando il sito è in un iframe di un altro dominio.
Aspetto del banner
Il banner v3 vive in uno Shadow DOM, che le regole CSS sulle classi .as-oil del banner v2 non raggiungono.
| Banner v2 | Banner v3 |
|---|---|
Regole CSS sulle classi .as-oil | Nessuna personalizzazione CSS supportata |
| Google Fonts caricati dal banner | Il banner non carica font esterni |
Il banner v2 caricava un Google Font con il caricamento automatico. Il banner v3 usa Arial di default, e il font del sito funziona solo se il sito lo carica già.
Aspetto, colori e font del banner v3 si impostano dalla dashboard. Le istruzioni sono nella guida Cookie banner.
Power Opt-In
Il banner v3 non ha il Power Opt-In, quindi ogni sito chiede il consenso per conto suo. La dashboard attivava il Power Opt-In in automatico sugli spazi web con più domini.
Condizioni di attivazione del TCF
Il banner v3 attiva il TCF solo se lo spazio web ha una di queste condizioni:
- almeno un fornitore IAB pubblicato;
- almeno un partner Google pubblicato;
- un fornitore personalizzato che dichiara finalità o special feature IAB.
Negli altri casi il banner v3 non genera la TC String e non offre l'API __tcfapi.
Il banner v2 offriva sempre __tcfapi e generava la TC String, anche senza fornitori IAB. Dopo la migrazione, su un sito senza queste condizioni __tcfapi non esiste più: uno script di terzi che la chiama non la trova.
Se uno script del sito chiama __tcfapi, pubblica prima i fornitori IAB che usa. Dopo il passaggio, in console typeof __tcfapi deve rispondere function.
Verifica
- Apri il sito in una finestra privata e apri la console del browser.
- Scrivi
typeof Avacy. La console deve rispondereobject. - Scrivi
typeof AVACY. Su uno spazio web migrato da v2 la console rispondeobject, per l'add-onlegacy-compat. Su uno spazio web creato con il banner v3 rispondeundefined. - Aggiungi alla pagina il listener della sezione Eventi.
- Premi Rifiuta tutto sul banner, o chiudilo con la X se manca il pulsante. Il listener deve scrivere
RejectAllin console. - Ricarica la pagina. Il banner non deve ricomparire.
Problemi comuni
I problemi più frequenti:
- Il banner non compare e la pagina ha due snippet: il vecchio snippet a tre tag e il tag unico sono nella stessa pagina. Togli il vecchio snippet;
- Il listener su
avacy_consentnon scatta: il banner v3 emetteavacy_consentsulwindow, quindi il listener deve stare sulwindow. Alla prima visita, prima della scelta, il banner v3 non emette niente. Il listener scatta dopo la prima scelta; - Il listener su
avacy_consentriceve elenchi di fornitori diversi dal v2: vedi Differenze diavacy_consent; - Il listener su
avacy_interactionoavacy_reject_allnon scatta più: il banner v3 non emette questi due eventi. Usaavacy:consent-saved; AVACYèundefinedsu uno spazio web creato con il banner v3:window.AVACYesiste solo sugli spazi web migrati. Usawindow.Avacy;Avacyèundefinedin uno script della pagina: lo script parte prima del loader. Aspettaavacy:ready;- Uno script marcato a mano resta bloccato: controlla che lo spazio web abbia fornitori con URL di blocco preventivo e che la marcatura non abbia
data-purposes,data-legintsodata-special-featuresvuoti; - Il visitatore rivede il banner dopo la migrazione: il banner v3 non legge il cookie
oil_data.
Ultimo aggiornamento: 10/11/2026.