Config reference

AvacyUserConfig (Partial<UserConfigType> + alcune estensioni Tier 1) è il payload accettato sia da <script type="application/json" id="avacy-config"> (auto-init), sia da window.Avacy.init(config) (programmatic). Tutte le chiavi qui sotto sono opzionali; i default vengono dal core (DEFAULT_CONFIG).

Source of truth nel codice:

packages/core/src/providers/providers.types.ts (ConfigType, UiConfig, StoreConfig, TcfFrameworkConfig, …)

packages/cmp-web/src/public-api.ts (AvacyUserConfig con core.autoInit)

packages/core/src/providers/config.ts (merge inline + remote config)

type AvacyUserConfig = Partial<UserConfigType> & {
  core?: Partial<UserConfigType['core']> & { autoInit?: boolean };
};

Identità e versionamento

Chiave	Tipo	Default	Descrizione
`publisherCountryCode`	`string` (ISO 3166-1 alpha-2)	`'IT'`	Country code del publisher, usato dal TCF (`publisherCC` nel TC string) e dalla logica di applicabilità di alcune normative locali.
`policyVersion`	`number`	`1`	Versione della policy interna. Cambiandola si invalida automaticamente il consenso salvato (forza un re-consent al prossimo boot).
`cmpVersion`	`string`	`'1.0.0'`	Versione del CMP scritta nel TC string. La libreria espone anche `window.Avacy.version` per il bundle vero (semver build).
`consentExpiryDays`	`number`	`182` (~6 mesi)	Scadenza del consenso in giorni. Un consenso più vecchio di tanto viene considerato non valido (`consent.valid: false`), il banner riappare.

Boot e auto-init

core?: {
  autoInit?: boolean;   // Tier 1 extension (cmp-web only)
  autoLoad?: boolean;   // core
}

Chiave	Tipo	Default	Descrizione
`core.autoInit`	`boolean`	`true`	Tier 1, gate del boot automatico del bundle cmp-web. Se `false`, il bundle non boota da solo e l'integratore deve chiamare `window.Avacy.init()`. Vedi anche il pattern programmatico nel Getting Started.
`core.autoLoad`	`boolean`	`true`	Core flag. Se `true`, al termine di `Core.init` viene invocato `triggerLoad()` (caricamento provider + emissione `OnLoad` listener chain). Se `false`, `triggerLoad` deve essere chiamato esplicitamente — uso avanzato, raro al di fuori dei test.

Lingua

Chiave	Tipo	Default	Descrizione
`language`	`LanguageCode` (ISO 639-1)	`'en'`	Lingua attiva al boot. Le label vengono lette dalla bundle prebundled, eventualmente sovrascritta da `customLabels[lang]` e/o dal remote labels file.
`autoLanguage`	`boolean`	`false`	Quando `true`, cmp-web rileva la lingua da `document.documentElement.lang` al boot e si riallinea ai cambi via `MutationObserver`. Mirror del flag `auto_language` di `avacy_banner`.
`customLabels`	`Partial<Record<LanguageCode, Partial<LanguageLabels>>>`	`undefined`	Override partiali delle label per lingua. Precedenza: `customLabels[lang]` > remote labels > prebundled[lang] > prebundled fallback. Chiavi sconosciute vengono mergiate ma loggate come warning.

Storage del consenso

store: {
  type: 'cookie' | 'local-storage' | (string & {});
  consentKey: string;
}

Chiave	Tipo	Default	Descrizione
`store.type`	`StoreType`	`'cookie'`	Implementazione di storage attiva. Built-in: `'cookie'`, `'local-storage'`. Per custom-store registrati via `registerStoreProvider` — il valore è opaco al core (`string & {}` accetta qualunque chiave registrata).
`store.consentKey`	`string`	`'avacy_consent'`	Nome della chiave dello storage (cookie name o localStorage key). Tipicamente lasciato di default per consistenza con la dashboard SaaS.

Asset path e remote config

Chiave	Tipo	Default	Descrizione
`assetPath`	`string`	`'/assets'`	Base path (o URL CDN) da cui il bundle fetcha tutti gli asset: remote config, GVL, ACM providers list, custom labels. Normalizzato a URL completo dal `ConfigProvider`. Esempi: `'/assets'`, `'https://cdn.example.com/cmp'`.
`remoteConfigName`	`string`	`'config.json'`	Filename del remote config sotto `assetPath`. Il fetch produce un `ConfigType` parziale, merge in shallow con quello inline (priorità: inline > remote).
`remoteGVLName`	`string`	`'v3'`	Cartella del GVL (Global Vendor List TCF) sotto `assetPath`. Usata per costruire `gvlUrl` quando non specificato esplicitamente in `frameworks[].tcf.gvlUrl`.
`vendorsCount`	`number`	derivato	Override del contatore vendor mostrato in alcune label ("X vendor partecipano…"). Se assente, viene calcolato a runtime dal framework provider attivo.

Frameworks

frameworks: FrameworkItem[];

type FrameworkItem =
  | FrameworkType                       // shorthand: 'tcf' | 'gcm' | 'custom' | 'acm'
  | { tcf: TcfFrameworkConfig }
  | { gcm: GcmFrameworkConfig }
  | { custom: CustomFrameworkConfig }
  | { acm: AcmFrameworkConfig };

Array di framework da attivare. Ogni entry può essere lo shorthand 'tcf' (usa i default del framework) oppure la forma a oggetto con la config full per quel framework. Default: [] (nessun framework attivo — boot minimal, raro nella pratica).

TCF (`frameworks: [{ tcf: { … } }]`)

Chiave	Tipo	Default	Descrizione
`cmpId`	`number`	`297`	CMP ID assegnato da IAB Europe. Per Avacy: `297`.
`frameworkVersion`	`number`	`2`	Versione TCF (`2` = TCF v2).
`vendors`	`number[] \| 'all'`	`'all'`	Lista vendor abilitati. `'all'` = tutti i vendor del GVL attivo.
`gvlUrl`	`string`	derivato da `assetPath` + `remoteGVLName`	URL completo del GVL JSON. Override esplicito se vuoi un GVL hostato altrove.
`purposeOneTreatment`	`boolean`	`true`	Flag TCF `purposeOneTreatment` (`pubCustomization`): indica se il purpose 1 (storage info) è trattato in modo speciale dal publisher.
`enableLegInt`	`'all' \| { purposes?, vendors? }`	(off)	Opt-in per legittimo interesse. Se omesso, nessun purpose o vendor è `legIntInteractable`. `'all'` = `{ purposes: 'all', vendors: 'all' }`.
`objectLegIntOnReject`	`boolean`	`true`	Su RejectAll: se `true`, azzera anche `hasLegitimateInterest`. Se `false`, lascia LI al valore corrente e flippa solo `hasConsent`.

GCM (`frameworks: [{ gcm: { … } }]`) — Google Consent Mode v2

Chiave	Tipo	Default	Descrizione
`enabled`	`boolean`	`false`	Abilita la propagazione `default → update` su `gtag('consent', …)`.
`remoteGVLName`	`string`	—	Override del nome cartella GCM-related asset sotto `assetPath`.
`mapToPurpose`	`GcmMapToPurposeEntry[]`	—	"Inferred mode": invece di esporre i 7 purpose GCM nel CPC, deriva il consenso GCM dagli altri framework. Ogni entry: `{ fw: 'tcf' \| 'custom' \| array, purpose: number \| number[], gcmPurpose: number[] }`. Con array su `fw`/`purpose`, tutte le sorgenti devono concedere (AND).

Custom (`frameworks: [{ custom: { … } }]`)

Chiave	Tipo	Default	Descrizione
`customVendorsUrl`	`string`	—	URL assoluto del JSON con vendor/purpose custom. Mutualmente esclusivo con `customVendorsConfigName`.
`customVendorsConfigName`	`string`	—	Filename del config custom sotto `assetPath`. Risolto come `assetPath + '/' + customVendorsConfigName`.
`customVendorsConfig`	`CustomVendorsConfig` (inline)	—	Config inline (evita la fetch HTTP). Utile per test e siti statici.
`customFetch`	`typeof fetch`	`window.fetch`	Override della funzione `fetch`. Usato per stubbing nei test e per piattaforme con `fetch` non standard.
`enableLegInt`	`'all' \| { purposes?, vendors? }`	(off)	Vedi `tcf.enableLegInt`, semantica identica.
`objectLegIntOnReject`	`boolean`	`true`	Vedi `tcf.objectLegIntOnReject`.

ACM (`frameworks: [{ acm: { … } }]`) — Google Additional Consent Mode

Chiave	Tipo	Default	Descrizione
`acmProvidersUrl`	`string`	—	URL assoluto della lista ATP (Google Additional Tech Provider).
`acmProvidersConfigName`	`string`	—	Filename ATP sotto `assetPath`.
`acmProvidersConfig`	`AcmProvidersConfig` (inline)	—	Config inline.
`acmFetch`	`typeof fetch`	`window.fetch`	Override fetch.

UI (`ui: UiConfig`)

Comportamento UX di banner first-layer e CPC second-layer. Funzionalità/logica del consenso NON vivono qui — sono in frameworks o nelle scelte UX vincolate dal TCF.

Chiave	Tipo	Default	Descrizione
`ui.closeWithoutConsents`	`false \| 'text' \| 'closeIcon'`	`false`	Azione "Continua senza accettare" nel banner. Funzionalmente equivalente a RejectAll. `'text'` = pulsante outline con testo; `'closeIcon'` = pulsante icon-only. Legacy `true` mappato a `'text'`.
`ui.secondLayerConsentOnGlobalSelection`	`boolean`	`false`	Se `true`, "Accetta tutto / Rifiuta tutto" nel CPC salva subito senza richiedere "Salva e continua".
`ui.activateVendorsOnLegalScopeSelections`	`boolean`	`false`	Se `true`, abilitare un purpose / special feature nel CPC abilita automaticamente i toggle dei vendor che lo supportano.
`ui.hideIntroOnScroll`	`boolean`	`false`	Se `true`, il sottotitolo sotto l'heading del CPC collassa (opacity → 0, height → 0) dopo > 100px di scroll nel pannello. Mirror del legacy `hide_intro_on_scroll`.
`ui.enableIframeDetection`	`boolean`	`true`	Se `true`, banner e CPC applicano automaticamente la variante "compatta" quando rilevano `window.self !== window.top`. `false` la disabilita (utile per editor in iframe che vogliono il layout standard). Inverso del legacy `block_iframe_layout`.
`ui.closePreferencesOnBulkSelect`	`boolean`	`true`	Se `true`, "Accetta tutto / Rifiuta tutto" nel preference center chiude il pannello dopo aver pubblicato il consenso. Se `false`, il pannello rimane aperto e si re-renderizza sul nuovo stato.

Logger

Chiave	Tipo	Default	Descrizione
`loggers`	`LoggerType[]` (`'console'`)	`[]` (silenzioso)	Quali logger attivare. `'console'` stampa info/warning/error su DevTools. Il valore può essere sovrascritto runtime via `window.Avacy.setDebug(true)` (persiste in `localStorage`, applicato al prossimo boot).

Filtri (advanced)

Chiave	Tipo	Default	Descrizione
`filters`	`ContextFilters`	—	Pipeline dichiarativa di filtri applicati da `CoreContext.setData` prima di scrivere il context e di notificare i subscriber. Una funzione per chiave del context, sync only. Uso avanzato — vedi `ContextFilters` nel core.

Esempio completo (TCF + custom + UI tweak)

{
  "publisherCountryCode": "IT",
  "language": "it",
  "policyVersion": 2,
  "consentExpiryDays": 365,
  "core": { "autoInit": true, "autoLoad": true },
  "store": { "type": "cookie", "consentKey": "avacy_consent" },
  "loggers": ["console"],
  "assetPath": "https://cdn.example.com/avacy",
  "remoteConfigName": "config.json",
  "frameworks": [
    {
      "tcf": {
        "cmpId": 297,
        "frameworkVersion": 2,
        "vendors": "all",
        "purposeOneTreatment": true,
        "enableLegInt": "all",
        "objectLegIntOnReject": true
      }
    },
    {
      "custom": {
        "customVendorsConfigName": "custom-vendors.json"
      }
    }
  ],
  "ui": {
    "closeWithoutConsents": "text",
    "closePreferencesOnBulkSelect": true,
    "enableIframeDetection": true
  },
  "customLabels": {
    "it": {
      "FIRST_LAYER_CONSENT_BUTTON": "Acconsento"
    }
  }
}

Identità e versionamento​

Boot e auto-init​

Lingua​

Storage del consenso​

Asset path e remote config​

Frameworks​

TCF (frameworks: [{ tcf: { … } }])​

GCM (frameworks: [{ gcm: { … } }]) — Google Consent Mode v2​

Custom (frameworks: [{ custom: { … } }])​

ACM (frameworks: [{ acm: { … } }]) — Google Additional Consent Mode​

UI (ui: UiConfig)​

Logger​

Filtri (advanced)​

Esempio completo (TCF + custom + UI tweak)​

See also​