Migrazione dal banner legacy
Per chi integrava il banner v2 (il banner "OIL", con window.AVACY): cosa cambia nel tag, negli eventi, nell'API globale, nella marcatura degli script e nello storage. Dove il v3 non ha un equivalente, la tabella lo dice.
La configurazione del banner (testi, colori, fornitori, framework) non si tocca a mano: la converte il SaaS quando il webspace passa al v3. Questa pagina riguarda solo quello che sta nel codice del sito.
Tag di installazione
Legacy — tre tag, con la config indicata dal primo:
<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 — un tag solo, il loader:
<script src="https://<tenant>.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=<uuid>"></script>
Il loader scarica da sé banner.json, il bundle e gli add-on. Lo stub __tcfapi e il default di Consent Mode, se il webspace usa TCF o GCM, sono già in testa al loader: la CDN serve la variante giusta. Con il template GTM "Avacy CMP" il default lo manda il template: il template imposta window.__AVACY_GTM_CONSENT_TEMPLATE__ e il loader salta il suo. Niente oilstub a parte. Il tag giusto per il webspace lo dà il SaaS, nella stessa schermata di prima. → Getting Started.
Se il sito ha già il tag unico non cambia nulla. Il SaaS dà il tag unico anche ai webspace ancora legacy: finché il webspace non migra, la CDN risponde con uno script piccolo ([avacy-loader-v2] in console) che carica oilstub.min.js e oil.min.js. Alla migrazione lo stesso URL serve il loader v3. Va sostituito solo il vecchio snippet a tre tag, che non deve restare nella pagina insieme al tag unico.
Eventi
Il v3 emette CustomEvent sul document con prefisso avacy: (→ Events). Gli eventi legacy (avacy_consent e avacy_interaction su window, i postMessage oil_*, eventCollection) non vengono emessi dal banner v3: un listener scritto per il legacy va riscritto. Eccezioni: l'add-on consent-event rimette avacy_consent su ogni webspace v3, e sui webspace migrati da v2 l'add-on legacy-compat rimette window.AVACY, così le integrazioni esistenti non si rompono. Il contenuto dell'evento ha poche differenze dal v2 (fornitori IAB, fornitori custom, optin, prima visita): sono nella tabella delle differenze.
| Legacy | v3 | Note |
|---|---|---|
window → avacy_consent | document → avacy:consent-saved | Il detail v3 è { type, timestamp, gcm }; il dettaglio per finalità/fornitore si legge con getConsent(). Il legacy emetteva avacy_consent anche a ogni caricamento di pagina con consenso già dato (trigger: 'page_load'); il v3 no: al boot usa avacy:ready + getConsent(). Su ogni webspace v3 consent-event lo rimette, ma alla prima visita, senza consenso salvato, non parte. |
avacy_consent → detail.gcm (array dei tipi concessi) | avacy:consent-saved → detail.gcm | Nel v3 è un oggetto con tutti e 7 i tipi a 'granted'/'denied', undefined senza GCM. |
dataLayer → { event: 'avacy_consent_update' } | dataLayer → { event: 'avacy_consent_update' } | Uguale al legacy, con GCM attivo: il core lo spinge subito dopo ogni gtag('consent', 'update', …), al caricamento con un consenso salvato (non alla prima visita, senza consenso) e a ogni scelta, anche dopo un rifiuto. Un trigger GTM su quell'evento continua a funzionare. Il default lo manda il loader (variante gcm) oppure, con GTM, il template "Avacy CMP"; gli update e l'evento il core. |
window → avacy_interaction (detail.optin: consent-all, reject-all, save-preferences, close-banner) | — | Nessun equivalente pubblico. avacy:consent-saved dice il tipo salvato, non il bottone premuto. |
postMessage oil-checked-optin | avacy:ready | Boot finito; lo stato del consenso con getConsent(). |
postMessage oil_shown | avacy:banner-shown | |
postMessage oil_optin_done, oil_soi_optin_done, oil_optout_done | avacy:consent-saved | Distinguere con detail.type (AcceptAll / RejectAll / Personalized). |
postMessage oil_click_advanced_settings | avacy:cpc-opened | Il v3 lo emette a ogni apertura del pannello, da qualunque punto. |
postMessage oil_close_banner_button_clicked, oil_optin_done_button_clicked, oil_as_cpc_privacy_selected | — | Nessun evento per il singolo click. La X del banner salva un RejectAll, quindi arriva avacy:consent-saved. |
eventCollection, isInCollection(name) | — | Nessuno storico degli eventi. Lo stato corrente si legge con getData() / getConsent(). |
API globale
L'oggetto globale cambia nome: da window.AVACY (alias di window.AS_OIL) a window.Avacy. Nel v3 esiste solo dopo l'avvio del banner (→ Lifecycle). Sui webspace migrati da v2 l'add-on legacy-compat mantiene window.AVACY per showPreferenceCenter e getPurposeConsents.
| Legacy | v3 | Note |
|---|---|---|
AVACY.showPreferenceCenter('absolute') | window.Avacy.showPreferenceCenter() | Pannello in overlay. Sui webspace migrati la vecchia chiamata funziona ancora: la copre legacy-compat. |
AVACY.showPreferenceCenter() / ('inline') | window.Avacy.showPreferenceCenter('#contenitore') | Il pannello inline nel v3 vuole un contenitore (selettore o elemento). Un selettore che non trova niente lancia un'eccezione. Sui webspace migrati legacy-compat apre l'overlay, anche per 'inline' e senza argomento; il contenitore #oil-preference-center del legacy non lo cerca. |
AVACY.showVendors() | window.Avacy.showPreferenceCenter(undefined, { section: 'vendor' }) | Apre il pannello sulla prima sezione fornitori. |
AVACY.acceptAll(), AVACY.triggerOptIn() | window.Avacy.acceptAll() | |
AVACY.triggerOptOut() | — | Il legacy cancellava i cookie del consenso. Il v3 non ha un'API che cancella il consenso; rejectAll() salva un rifiuto. |
AVACY.changeLanguage(lang) | window.Avacy.changeLanguage(lang) | |
AVACY.reload() | window.Avacy.reload() | Il v3 non riscarica banner.json. |
AVACY.verboseModeOn() / verboseModeOff() | window.Avacy.debugModeOn() / debugModeOff() | Nel v3 il flag sta in localStorage (avacy:debug), non in un cookie. |
AVACY.getPurposeConsents(), getLegIntConsents(), hasConsents(…), getCustomVendors(), getOilConsent() | window.Avacy.getConsent() | Una chiamata sola: mappe purposes/vendors per il consenso, choices per il legittimo interesse. Sui webspace migrati legacy-compat risponde ancora a getPurposeConsents(). |
AVACY.previewModeOn() / previewModeOff() | — | Nessun equivalente. |
Altri metodi (readLocalstorage, clearVendorlistCaches, getLegalText, getFullConfiguration, …) | — | Nessun equivalente diretto; la config attiva si legge con getData().config. |
Blocco preventivo
Nel v3 lo sblocco lo fa l'add-on preemptive-block, che il SaaS accende quando un fornitore custom del webspace ha URL di blocco preventivo. La marcatura legacy continua a funzionare: l'add-on legge anche gli elementi con data-managed="as-oil" e traduce gli attributi per nome. Non serve riscrivere i siti marcati col plugin precedente o a mano.
Nel legacy data-purposes="", data-legints="" e data-special-features="" (presenti ma vuoti) volevano dire "tutti gli id di quell'asse". Il v3 non ha una forma "tutti": questi attributi vuoti lasciano l'elemento bloccato, e la console lo segnala con un avviso [Avacy] Preemptive block. Queste marcature vanno riscritte elencando gli id.
data-iab-vendor="" e data-custom-vendor="" vuoti invece non richiedono niente, come nel legacy: l'elemento parte dopo la prima scelta del visitatore, anche con "Rifiuta tutto".
Per marcature nuove, il formato v3:
| Legacy | v3 |
|---|---|
type="as-oil" | type="text/avacy-blocked" (qualunque type non eseguibile va bene) |
data-managed="as-oil" | data-avacy-requires="…" (è l'attributo che marca) |
data-src="…" | data-avacy-src="…" |
data-type="text/javascript" | data-avacy-type="…" (facoltativo: assente = script classico) |
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 ; in un solo attributo, tutti in AND. L'esempio della guida legacy:
<!-- legacy -->
<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 -->
<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>
Il v3 aggiunge assi che il legacy non aveva (gcm:purpose:4, acm:vendor:…, custom:purpose:…) e una regola per i framework non configurati: sintassi completa.
Storage
| Legacy | v3 | |
|---|---|---|
| Chiave del consenso | oil_data | avacy_consent (store.consentKey), cookie o localStorage secondo store.type |
| Id dell'archivio consensi | campo consent_id dentro oil_data | campo dentro avacy_consent: meta.consentId → consent-archive |
Il v3 non legge oil_data: un visitatore che aveva già scelto col banner legacy rivede il banner alla prima visita col v3. Lo stesso vale per chi arriva da un'altra CMP: vedi Durata del consenso. Script del sito che leggevano direttamente oil_data vanno riscritti con getConsent(): il contenuto di avacy_consent è un formato interno, non un'API.
Legittimo interesse
| Legacy | v3 |
|---|---|
use_legint: true (config del banner OIL) | enableLegInt: 'all' sul framework (tcf, custom). Il SaaS fa questa conversione. |
disableLegInt: { purposes, vendors } (prime versioni di cmp-web, vedi Legitimate interest and filter pipeline) | enableLegInt: { purposes, vendors } — logica invertita: ora il legittimo interesse è spento di default e si accende per gli elementi elencati (o 'all'). |
Prima di cambiarlo leggi Base giuridica del legittimo interesse: enableLegInt cambia quello che il CMP scrive nella TC String, non solo la UI.