Avacy CMP Web v3 — Preview

Preview tecnica. Questa sezione documenta la nuova superficie pubblica di @avacy/cmp-web v3 ed è accessibile solo via URL diretto — non compare nella sidebar né nella search della doc. Il v3 è già collegato al SaaS (loader v3 + banner.json del webspace); cosa promuovere a documentazione pubblica si decide più avanti.

La libreria @avacy/cmp-web è il banner di consenso GDPR/IAB-TCF di Avacy, distribuita come bundle CDN. Si installa con un solo tag (il loader v3), che scarica la configurazione del webspace pubblicata dal SaaS. Espone un'unica superficie pubblica accessibile sia da window.Avacy (uso classico via tag) sia via import del bundle (uso advanced per chi scrive storage custom o build enterprise).

Indice della documentazione

Guides

• Getting Started — installazione, primo banner in 30 secondi
• Add-on — blocco preventivo degli script, archivio consensi, stub TCF
• Migrazione dal banner legacy — eventi, API globale e marcatura degli script: cosa cambia rispetto al banner v2

Reference (Tier 1 — common API)

Tutto su window.Avacy.*, semver-stabile.

• Config reference — tutte le chiavi di AvacyUserConfig (store, core, frameworks, ui, customLabels, …)
• Lifecycle — init, reload, getData, version
• Consent actions — acceptAll, rejectAll, triggerConsent, updateConsent
• UI control — showPreferenceCenter, closePreferenceCenter, changeLanguage
• Consent query — getConsent (3 viste: macro + mappa purposes/vendors + array choices)
• Debug — setDebug
• Events — DOM CustomEvent su document

Reference (Tier 2 — advanced)

Solo via import { … } from '@avacy/cmp-web'. Etichettato @beta — può breakare in minor.

• Tier 2 reference — init della libreria, registerStoreProvider, CoreEvents, types

Internals — motore interno, non è API pubblica

Non è superficie chiamabile dall'esterno: è come funziona @avacy/core e @avacy/cmp-web sotto Tier 1/Tier 2. Punto di partenza per decidere col PO cosa, se qualcosa, promuovere a pubblico — oggi è privata per intero.

• Core — bootstrap, storage, framework di consenso — ciclo di vita interno, merge della config, listener del consenso, sistema add-on, selezione dello storage (cookie/local-storage) e suoi limiti noti, meccaniche di TCF/GCM/ACM/Custom, disclosure, logger
• cmp-web — componenti e accessibilità interna — init/reload e sorgenti di config, banner/CPC/shield, add-on consent-archive, meccanismi a11y non esposti via config (focus trap, live region, virtualizzazione), ambiente di esecuzione
• Build e pubblicazione — pacchetto web, loader v3, pipeline CDN /v3/, cmp-saas-preview, RAI (v2-compat, bridge nativo, syndication)

---

Quickstart

Il tag di installazione si copia dal SaaS: <tenant> e <uuid> sono quelli del webspace.

<script src="https://<tenant>.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=<uuid>"></script>

<script>
  document.addEventListener('avacy:consent-saved', (e) => {
    console.log('user saved consent:', e.detail.type, e.detail.gcm);
  });
</script>

La configurazione (framework, fornitori, testi, colori, add-on) arriva dal banner.json che il SaaS pubblica per il webspace. Un blocco #avacy-config nella pagina può sovrascriverne singole chiavi: vedi precedenza tra le sorgenti.

Versionamento

Tier	Stabilità	Cycle
Tier 1 (window.Avacy.*, avacy:* events, UserConfigType)	Semver strict	Deprecation: 1 MINOR con console.warn + TSDoc @deprecated → rimozione in MAJOR
Tier 2 (import { … })	Beta	Può breakare in MINOR. Annuncio su Slack #avacy-dev 1 settimana prima

Versione bundle: window.Avacy.version (es. "3.0.0").