Lifecycle

Stato, boot programmatico e re-mount del CMP a runtime.

Method / Property	Tier	Since
init(config?)	1	3.0
reload()	1	3.0
getData()	1	3.0
version (property)	1	3.0
'avacy:ready' (event)	1	3.0

Chi avvia il CMP dipende da come lo includi, e window.Avacy nasce solo dentro init():

• Loader v3 (il tag /v3/avacy-cmp-web.js?webspace=… copiato dal SaaS): scarica banner.json e il bundle e chiama init() da sé. È il caso normale.
• cmpweb-web.auto.esm.js (inclusione manuale, senza SaaS): stessa libreria più la chiamata a init() al caricamento.
• cmpweb-web.esm.js importato come libreria: non avvia nulla. Il boot parte quando chiami tu init() dall'import; fino a quel momento window.Avacy non esiste.

→ Esempi delle tre modalità in Getting Started.

---

init

Avvia il CMP: legge e fonde le sorgenti di config, inizializza il core, monta banner o shield, emette avacy:ready.

// import della libreria (cmpweb-web.esm.js)
init(config?: AvacyUserConfig): Promise<void>

// dopo il primo boot, anche come
window.Avacy.init(config?: AvacyUserConfig): Promise<void>

Parameters

Name	Type	Description
config	AvacyUserConfig (opzionale)	La sorgente più forte: vince sul flag di debug, su window.avacyFilters, sul blocco #avacy-config e su banner.json. Merge profondo sugli oggetti ({ ui: { behavior: {...} } } tiene ui.colors), gli array (frameworks, addons, …) sostituiscono. Vedi precedenza.

Tre modi di avviare il CMP

Inclusione	Chi chiama init()	Config
Loader v3	il loader, appena ha banner.json e il bundle	banner.json + #avacy-config in pagina
cmpweb-web.auto.esm.js	il bundle stesso, al caricamento	#avacy-config in pagina
cmpweb-web.esm.js importato	tu, quando vuoi	#avacy-config in pagina + l'argomento config

core.autoInit non governa nessuna di queste tre: loader e .auto chiamano init() senza leggerlo. Conta solo per il loader Stencil dist di @avacy/cmp-web (quello dietro un bundler), dove core.autoInit: false nel #avacy-config impedisce il boot automatico. Vedi core.autoInit.

Idempotenza

init() non fa nulla se trova già avacy-banner o avacy-shield nella pagina. Quindi una seconda chiamata dopo il primo boot, con o senza config, è un no-op: per riavviare con la config riletta usa reload().

Example

<script type="application/json" id="avacy-config">
  { "publisherCountryCode": "IT", "language": "it",
    "assetPath": "https://<tenant>.avacy-cdn.com/v3/web/<versione>/assets",
    "frameworks": [{ "tcf": { "cmpId": 297, "frameworkVersion": 2, "vendors": "all" } }] }
</script>
<script type="module">
  import { init } from 'https://<tenant>.avacy-cdn.com/v3/web/<versione>/cmpweb-web.esm.js';

  document.addEventListener('hero:animation-done', () => {
    init({ language: 'en' });  // boot adesso, con un override che vince su #avacy-config
  });
</script>

L'override { language: 'en' } vale solo perché è il primo boot. Chiamato dopo, init({ language: 'en' }) non cambia niente: per la lingua c'è changeLanguage.

⚠️ Caveat: gating dei vendor

Posticipare l'init del CMP significa posticipare il consent gate. I vendor (Google Analytics, Meta Pixel, third-party SDK) che si inizializzano prima che init() abbia risolto non vedono il consenso, leggono lo stub __tcfapi o lo dataLayer vuoto, e possono tracciare in modo non conforme GDPR.

Se avvii tu il CMP, è tua responsabilità non istanziare vendor prima che init() risolva (o usare avacy:ready come gate per il loro mount).

---

reload

Distrugge e rimonta tutto il CMP partendo dalla config corrente: reinizializza i provider, rimonta gli elementi UI. Non azzera il consenso salvato (quello resta nello store).

window.Avacy.reload(): Promise<void>

Behavior

1. Emette avacy:banner-hidden { reason: 'destroy' }, sempre: anche se in pagina c'era solo lo shield.
2. Ferma l'osservatore di <html lang> (quello di autoLanguage); init() lo riaccende.
3. Unmount di avacy-banner, avacy-shield, avacy-cpc (qualunque sia montato) e reset di cpcOpen: false.
4. Rientra in init(): reinizializzazione dei provider (store, framework, language) e degli add-on.
5. Re-mount condizionale:
   • se il consenso salvato è ancora valido (con la config appena riletta) → mount avacy-shield (salvo ui.behavior.showShield: false)
   • altrimenti → mount avacy-banner ed emissione di avacy:banner-shown { layer: 'first' }
6. Emette avacy:ready.

Sequenza degli eventi: avacy:banner-hidden { reason: 'destroy' } → (avacy:banner-shown { layer: 'first' } solo se manca un consenso valido) → avacy:ready.

Example

// dopo aver cambiato il blocco #avacy-config in pagina (es. policyVersion più alta):
await window.Avacy.reload();

When to use it

• Applicare un #avacy-config modificato in pagina (es. un policyVersion più alto che invalida il consenso salvato)
• Test/preview in cui resetti il consenso programmaticamente e vuoi ri-mostrare il banner
• Integrazioni SPA che cambiano vista privacy-sensibile

When NOT to use it

• Cambio del consenso → usa triggerConsent o updateConsent (non serve reload)
• Cambio lingua → changeLanguage. Un reload() dopo changeLanguage riporta la lingua a quella della config (language, o a quella di <html lang> con autoLanguage), perché init() la reimposta al boot.
• Riprendere un banner.json appena pubblicato dal SaaS → reload() non lo riscarica (vedi sotto): serve un caricamento di pagina.

La versione corrente di reload() è minimal: destroy e reinit. Rilegge #avacy-config, window.avacyFilters e il flag di debug, e riparte dal banner.json del primo boot, senza riscaricarlo: vendors, frameworks e add-on restano. L'argomento passato a init(config) non viene riapplicato.

---

getData

Ritorna uno snapshot read-only dei dati del CMP a un istante: config, consent, language, UI state, customization, glossary.

window.Avacy.getData(): Readonly<CmpData> | null

Ritorna null se il CMP non è ancora inizializzato.

Return shape

type CmpData = ContextData & {
  ui: { cpcOpen: boolean };
};

ContextData è il bucket interno del core con core, config, storage (tipo/tecnologia di storage effettivamente in uso — es. 'cookie', utile quando la view deve mostrare la label risolta invece della sola chiave di config), language, consent, customization, glossary, stacks (stack IAB risolti, vuoto se nessun framework configura una whitelist), standardTexts (testi standard che il framework impone accanto a un'intera sezione, oggi quelli TCF delle Features), decodedConsent?, acmAddtlConsent?.

→ Vedi CmpData in Tier 2 per i type dettagliati.

Example

const data = window.Avacy.getData();
if (data?.consent.ready && data.consent.valid) {
  console.log('saved type:', data.consent.type);
}
console.log('CPC currently open?', data?.ui.cpcOpen ?? false);

See also

• getConsent() — proiezione user-friendly del solo consent
• CmpData — shape completa

---

version

Stringa con la versione del bundle (semver). Utile per debug e per matrici di compat clienti.

window.Avacy.version: string  // e.g. "3.0.0"

console.log('Avacy CMP', window.Avacy.version);

---

Event: avacy:ready

Emesso una volta, dopo che l'init del CMP ha completato e l'UI è (eventualmente) mountata. Rie-emesso dopo ogni reload().

document.addEventListener('avacy:ready', () => {
  console.log('Avacy ready', window.Avacy.version);
});

È sicuro registrare il listener dopo che il bundle ha caricato: i DOM event listener tardivi non perdono l'evento se sono registrati prima dell'effettivo dispatch (e il dispatch avviene a fine boot). Però se hai necessità di setup pre-boot, registra il listener nell'<head> prima del bundle script.