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, gli add-on e (se il webspace usa TCF) lo stub __tcfapi: niente oilstub a parte. Il tag giusto per il webspace lo dà il SaaS, nella stessa schermata di prima. → Getting Started.
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.
| 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(). |
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' } | — | Nessun equivalente: il v3 spinge solo gtag('consent', 'default' / 'update', …). Un trigger GTM su quell'evento va rifatto (es. con un listener su avacy:consent-saved che fa il proprio dataLayer.push). |
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).
| Legacy | v3 | Note |
|---|---|---|
AVACY.showPreferenceCenter('absolute') | window.Avacy.showPreferenceCenter() | Pannello in overlay. |
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. |
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. |
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.
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. 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.