Skip to main content

Getting Started

In 30 secondi: un tag nell'<head> + un listener sul consenso.

1. Installa il tag​

Copia dal SaaS il tag di installazione del webspace e incollalo nell'<head>, prima degli script dei fornitori:

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

È uno script classico (non serve type="module") e funziona anche iniettato da Google Tag Manager. Il tag punta al loader v3, che fa tutto da solo sullo stesso host:

  1. scarica in parallelo la configurazione del webspace (/config/<tenant>/<uuid>/banner.json, pubblicata dal SaaS) e il bundle del banner;
  2. scarica gli add-on accesi nel webspace. Lo stub TCF e il default di Consent Mode, se il webspace usa TCF o GCM, li ha già eseguiti in testa: la CDN serve la variante del loader adatta al webspace;
  3. avvia il banner.

Il banner viene montato automaticamente. Se il consenso è già stato dato in una visita precedente, viene montata invece l'icona "shield" (riapre le preferenze).

Niente configurazione, niente banner. Se banner.json non si scarica (webspace inesistente, banner disattivato dal SaaS, errore di rete) o il tag non ha ?webspace=, il loader scrive il motivo in console ([avacy-loader] …) e si ferma: non parte nessun banner con i default.

2. (Opzionale) Sovrascrivi qualcosa dalla pagina​

La configurazione arriva dal SaaS. Per cambiare singole chiavi su una pagina specifica, aggiungi un blocco #avacy-config (JSON) prima del tag:

<script type="application/json" id="avacy-config">
  { "language": "en" }
</script>
<script src="https://<tenant>.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=<uuid>"></script>

Il blocco vince su banner.json con un merge profondo sugli oggetti; gli array (frameworks, addons, …) sostituiscono. → Precedenza tra le sorgenti · Config reference.

3. Ascolta il consenso​

document.addEventListener('avacy:consent-saved', (event) => {
  const { type, timestamp, gcm } = event.detail;
  console.log(`user saved consent (${type}) at`, new Date(timestamp));

  // gcm: gli stati Google Consent Mode, se il webspace usa GCM
  if (gcm?.analytics_storage === 'granted') initAnalytics();
});

→ Tutti gli eventi disponibili: vedi Events.

4. (Opzionale) Apri il pannello preferenze a richiesta​

Esponi un link "Gestisci consenso" nel footer:

<a href="#" onclick="window.Avacy.showPreferenceCenter(); return false;">
  Gestisci consenso
</a>

→ Tutti i metodi UI: vedi UI control.

5. (Opzionale) Blocca gli script fino al consenso​

Gli script di terze parti si marcano nell'HTML e partono solo quando il visitatore dà il consenso che serve. Richiede l'add-on preemptive-block acceso nel webspace:

<script type="text/avacy-blocked"
        data-avacy-src="https://www.googletagmanager.com/gtag/js?id=G-XXXX"
        data-avacy-requires="gcm:purpose:4"></script>

gcm:purpose:4 è il purpose Google Consent Mode analytics_storage: lo script parte solo quando il visitatore lo concede. Il webspace deve avere GCM tra i framework: un requisito su un framework non configurato tiene l'elemento bloccato.

→ Sintassi completa: vedi Add-on › Blocco preventivo.

Esempio end-to-end​

<!DOCTYPE html>
<html lang="it">
<head>
  <meta charset="utf-8">
  <title>Esempio Avacy CMP</title>

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

  <a href="#" onclick="window.Avacy.showPreferenceCenter(); return false;">
    Gestisci consenso
  </a>

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

Senza SaaS: inclusione manuale del bundle​

Per una pagina che non usa un webspace del SaaS (prove, build custom), il bundle si include a mano da un path versionato, con la config tutta in pagina. Tre tag nel <head>, in quest'ordine:

<!-- 1. Config: un solo blocco per pagina, id `avacy-config`, MIME JSON. -->
<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>

<!-- 2. Stub TCF: solo se `frameworks` include tcf. Sincrono, prima di qualunque script che chiami __tcfapi. -->
<script src="https://<tenant>.avacy-cdn.com/v3/web/<versione>/tcf-stub.js"></script>

<!-- 3. Il banner, con avvio automatico. -->
<script type="module" src="https://<tenant>.avacy-cdn.com/v3/web/<versione>/cmpweb-web.auto.esm.js"></script>

assetPath serve per le etichette nelle lingue diverse da it/en/de (già incluse nel bundle) e per le immagini (shield, watermark). In questa modalità gli add-on non si scaricano da soli: li carica il loader, che qui non c'è.

Con GCM in frameworks il bundle manda solo gli update: il default di Consent Mode lo manda il loader, che qui non c'è. Va messo in pagina prima dei tag Google, come fa la variante gcm del loader: gtag('consent', 'default', { …tutti e 7 i tipi: 'denied', wait_for_update: 500 }).

Boot programmatico​

Per decidere tu il momento esatto in cui il banner appare (animazioni hero, SPA, config asincrona), importa cmpweb-web.esm.js: è la stessa libreria senza avvio automatico. window.Avacy nasce alla prima chiamata di init().

<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: 'it' });
  });
</script>

⚠️ Posticipare l'avvio significa posticipare il consenso. I fornitori che partono prima che init() abbia risolto non vedono nessun consenso. Non istanziarli prima di avacy:ready. → Dettagli: init.

Prossimi passi​