Passa al contenuto principale

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.

Per migrare lo spazio web

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_interaction o avacy_reject_all. Il listener su avacy_consent e i due metodi AVACY.showPreferenceCenter e AVACY.getPurposeConsents continuano 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​

  1. Se il sito ha lo snippet a tre tag, sostituiscilo con il tag unico (tabella Snippet).
  2. Riscrivi ogni uso di AS_OIL, oil_data e degli altri metodi di AVACY con le tabelle API e Storage.
  3. Riscrivi i listener con la tabella Eventi. I listener su avacy_consent restano, e vanno solo controllati.
  4. Controlla gli script marcati a mano con la tabella Blocco preventivo.
  5. Togli il CSS scritto sulle classi .as-oil (sezione Aspetto).
  6. 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.

Un solo snippet per pagina

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 v2Banner 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 v2Banner v3Note
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 equivalenteIl banner v3 non tiene uno storico. Lo stato si legge con Avacy.getConsent().
AVACY.readLocalstorage(), clearVendorlistCaches() e gli altri metodi interniNessun 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 v2Banner v3Note
window → avacy_consent con detail.trigger === 'consent_update' o 'page_load'window → avacy_consent, con gli stessi triggerNon 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-savedAlternativa 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-loadedAlternativa 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.gcmSolo 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_interactionNessun equivalenteavacy:consent-saved dà il tipo di consenso (detail.type), non il pulsante premuto.
window → avacy_reject_allNessun equivalenteIl 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_showndocument → avacy:banner-shown
postMessage oil_click_advanced_settingsdocument → avacy:cpc-opened
postMessage oil-checked-optinNessun equivalente direttoIl 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_doneavacy:consent-savedDistingui i casi con detail.type (AcceptAll, RejectAll, Personalized).
postMessage oil_close_banner_button_clicked, oil_optin_done_button_clicked, oil_as_cpc_privacy_selectedNessun equivalenteIl 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>

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 casoBanner v2Banner v3
customVendorsWithConsentContava solo le finalità, e ignorava il consenso al fornitoreIl fornitore entra con il consenso al fornitore e a tutte le finalità che dichiara
iabVendorsWithConsentIl fornitore entrava solo con tutte le finalità accettateBasta il consenso al fornitore
optintrue in ogni consenso salvato, anche dopo Rifiuta tuttofalse dopo un rifiuto totale: Rifiuta tutto, la X, Continua senza accettare o preferenze salvate con tutto spento
Prima visita, senza sceltapage_load con optin: false e liste vuoteNessun 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.

Attributi v2 presenti ma vuoti

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.

Siti col plugin WP 1.3.1

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 v2Banner 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 v2Banner v3
Nome del cookie del consensooil_dataavacy_consent
Attributo SameSiteNone (con Secure, su https)Lax
Duratacookie_expires_in_daysLa 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 v2Banner v3
Regole CSS sulle classi .as-oilNessuna personalizzazione CSS supportata
Google Fonts caricati dal bannerIl 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​

  1. Apri il sito in una finestra privata e apri la console del browser.
  2. Scrivi typeof Avacy. La console deve rispondere object.
  3. Scrivi typeof AVACY. Su uno spazio web migrato da v2 la console risponde object, per l'add-on legacy-compat. Su uno spazio web creato con il banner v3 risponde undefined.
  4. Aggiungi alla pagina il listener della sezione Eventi.
  5. Premi Rifiuta tutto sul banner, o chiudilo con la X se manca il pulsante. Il listener deve scrivere RejectAll in console.
  6. 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_consent non scatta: il banner v3 emette avacy_consent sul window, quindi il listener deve stare sul window. Alla prima visita, prima della scelta, il banner v3 non emette niente. Il listener scatta dopo la prima scelta;
  • Il listener su avacy_consent riceve elenchi di fornitori diversi dal v2: vedi Differenze di avacy_consent;
  • Il listener su avacy_interaction o avacy_reject_all non scatta più: il banner v3 non emette questi due eventi. Usa avacy:consent-saved;
  • AVACY è undefined su uno spazio web creato con il banner v3: window.AVACY esiste solo sugli spazi web migrati. Usa window.Avacy;
  • Avacy è undefined in uno script della pagina: lo script parte prima del loader. Aspetta avacy: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-legints o data-special-features vuoti;
  • Il visitatore rivede il banner dopo la migrazione: il banner v3 non legge il cookie oil_data.

Ultimo aggiornamento: 10/11/2026.