Passa al contenuto principale

Snippet HTML

Lo snippet HTML è una riga di codice da incollare nel <head> delle pagine del sito. Carica il banner dalla CDN di Avacy.

A chi serve​

Serve a chi può modificare l'HTML del sito, per esempio un sito scritto a mano o con un tema modificabile. Per Shopify, Magento e HubSpot esistono pagine dedicate che usano lo stesso snippet.

Il plugin WordPress e Google Tag Manager hanno un'installazione propria, descritta nelle guide Installare il banner con il plugin WordPress e Installare il banner con Google Tag Manager.

Prerequisiti​

Prima di cominciare ti servono:

  • uno spazio web nella dashboard di Avacy, con il banner pubblicato da Salva e pubblica Cookie Banner. Il loader legge la configurazione da un file che la dashboard scrive alla pubblicazione;
  • l'accesso al codice del <head> delle pagine del sito.

Step​

  1. Nella dashboard apri la pagina Cookie banner dello spazio web e premi Integra il banner sul tuo spazio web. In alternativa apri le impostazioni dello spazio web e scegli Integrazione di Avacy sul tuo spazio web.

    Pagina Integrazione di Avacy sul tuo spazio web, scheda Integra Avacy, con la voce Codice HTML aperta e il pulsante Copia codice

  2. Apri la scheda Integra Avacy, poi la voce Codice HTML.

  3. Premi Copia codice. La dashboard copia uno snippet come questo.

    <script src='https://acme.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=123e4567-e89b-12d3-a456-426614174000'></script>

    Nello snippet vero, acme è il nome del tuo Team e il codice dopo webspace= è l'identificativo del tuo spazio web. Copia lo snippet così com'è. Questi valori di esempio compaiono in tutta la documentazione.

  4. Apri il file che contiene il <head> delle pagine. Con un tema o un template, apri il <head> condiviso da tutte le pagine.

  5. Incolla lo snippet subito dopo l'apertura del tag <head>.

    <head>
    <script src='https://acme.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=123e4567-e89b-12d3-a456-426614174000'></script>
    <meta charset="utf-8">
    <!-- altri tag del sito -->
    </head>
  6. Salva il file e pubblica la modifica sul sito.

Il banner si avvia da solo e non richiede altro codice. Il loader funziona anche inserito da Google Tag Manager.

Verifica​

Apri il sito in una finestra privata. Il banner compare alla prima visita. Il controllo completo è in Verificare che il banner funzioni.

Dove mettere lo snippet​

Il loader scarica dal proprio indirizzo la configurazione dello spazio web e il codice del banner, poi avvia il banner. La CDN sceglie la versione del loader adatta allo spazio web.

Un tag <script> senza async e senza defer ferma la lettura della pagina finché il file non è eseguito. Il loader esegue subito queste azioni, prima dei tag che lo seguono:

  • imposta lo sviluppatore (developer ID) di Avacy per Google con un comando gtag;
  • con Google Consent Mode, scrive nel dataLayer il valore iniziale "negato" di ogni tipo di consenso. Il valore deve esistere prima che un tag Google legga lo stato del consenso;
  • con TCF di IAB, installa la funzione __tcfapi, che i fornitori della pagina possono chiamare subito.

Per questo lo snippet va in alto nel <head>, prima dei tag Google e degli script che usano TCF.

Il resto aspetta la fine della lettura della pagina (evento DOMContentLoaded). Solo allora il loader scarica la configurazione e il codice del banner. Così Firefox applica anche l'import map che alcuni siti stampano dopo lo snippet, per esempio WordPress con un tema a blocchi. Se il loader arriva a pagina già letta, per esempio da Google Tag Manager, parte subito.

Pagina con tag Google​

Metti lo snippet prima di gtag.js e di analytics.js. Se un tag Google parte prima del valore iniziale di Consent Mode, il banner scrive un avviso nella console, descritto in Ordine dei tag Google e debug mode.

Pagina con Google Tag Manager e TCF​

Lo snippet va dopo Google Tag Manager. Prima di Google Tag Manager va lo stub TCF, un piccolo script che installa __tcfapi.

<head>
<!-- 1. Stub TCF, sincrono -->
<script src="https://acme.avacy-cdn.com/v3/tcf-stub.js"></script>

<!-- 2. Snippet di Google Tag Manager -->

<!-- 3. Snippet di Avacy -->
<script src='https://acme.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=123e4567-e89b-12d3-a456-426614174000'></script>
</head>

Se __tcfapi esiste già nella pagina, lo snippet non aggiunge il suo stub.

Pagina con il template GTM di Avacy​

Il template GTM imposta da solo il valore iniziale di Consent Mode. Il loader lo riconosce e salta il proprio valore.

Domini da autorizzare nella Content Security Policy​

Se il sito usa una Content Security Policy (CSP), la CSP deve autorizzare questi indirizzi. La colonna "Direttiva" indica la direttiva che governa ogni richiesta.

IndirizzoA cosa serveDirettiva
https://<team>.avacy-cdn.comLoader, codice del banner e componenti aggiuntivi del banner (file .js). Non serve se script-src usa il nonce, vedi Script con noncescript-src
https://<team>.avacy-cdn.comConfigurazione dello spazio web, traduzioni delle lingue che il banner non includeconnect-src
https://<team>.avacy-cdn.comImmagini del banner, come l'icona delle preferenzeimg-src
https://assets.avacy-cdn.comElenchi dei fornitori TCF e dei fornitori Google, solo con quei framework attiviconnect-src
https://assets.avacy-cdn.comLogo caricato dalla dashboardimg-src
https://api.avacy.euInvio dei consensi all'archivio consensi, solo se l'archiviazione automatica è attivaconnect-src

<team> è il nome del Team, lo stesso che compare nello snippet (acme negli esempi).

Stili del banner​

Il banner non chiede di aggiungere 'unsafe-inline' a style-src. Nei browser attuali il banner applica i propri stili in un modo che la CSP non blocca.

Safari prima della versione 16.4 non supporta quel modo. Lì il banner aggiunge un elemento <style> con il nonce dello snippet o del tag <meta name="csp-nonce" content="…">. Con un style-src rigido, quindi, metti il nonce sullo snippet come in Script con nonce, oppure aggiungi quel tag <meta>.

Se la CSP blocca comunque gli stili, il banner non mostra niente: né il banner, né l'icona delle preferenze, né la finestra delle preferenze. Così la pagina resta usabile. Il consenso già salvato e il blocco preventivo continuano a funzionare. La console mostra l'avviso "The banner styles were blocked by the Content-Security-Policy…" con la correzione da fare.

Esempio di CSP senza nonce con cui il banner funziona, anche con il TCF attivo (acme è il nome del Team). Se usi l'archiviazione automatica dei consensi, aggiungi https://api.avacy.eu a connect-src.

default-src 'self';
script-src 'self' https://acme.avacy-cdn.com;
connect-src 'self' https://acme.avacy-cdn.com https://assets.avacy-cdn.com;
img-src 'self' https://acme.avacy-cdn.com https://assets.avacy-cdn.com data:;
style-src 'self'

Script con nonce​

Se script-src accetta solo gli script con un nonce, metti lo stesso nonce sullo snippet. Il banner usa quel nonce per caricare il proprio codice e i componenti aggiuntivi. In questo caso l'indirizzo della CDN non serve in script-src.

<script nonce="R4nd0m" src='https://acme.avacy-cdn.com/v3/avacy-cmp-web.js?webspace=123e4567-e89b-12d3-a456-426614174000'></script>

Ti consigliamo di aggiungere 'strict-dynamic': il browser autorizza da solo gli script caricati da uno script con il nonce.

script-src 'nonce-R4nd0m' 'strict-dynamic'

Il blocco preventivo sblocca gli script dopo il consenso e mantiene il loro nonce. Gli script marcati per il blocco preventivo devono quindi avere il nonce del sito. Senza nonce, la CSP blocca lo script anche dopo il consenso.

Problemi comuni​

SintomoCausa probabileCosa fare
Il banner non compareLo spazio web non ha il banner pubblicato, oppure lo snippet usa un codice sbagliatoControlla la console come in Verificare che il banner funzioni
L'avviso "Google tags ran before…" compare nella consoleUn tag Google parte prima dello snippetSposta lo snippet sopra i tag Google
Il banner compare solo su alcune pagineLo snippet è in un file che non tutte le pagine usanoIncolla lo snippet nel file del <head> condiviso
La console mostra errori di rete verso avacy-cdn.comLa CSP del sito blocca l'indirizzoAutorizza gli indirizzi della tabella
Con il TCF il banner compare, ma «Accetta cookie» non salva la scelta e le preferenze sono vuote. La console mostra The site's Content Security Policy blocks https://assets.avacy-cdn.com…La CSP blocca l'elenco dei fornitori TCFAggiungi https://assets.avacy-cdn.com a connect-src
Il banner non compare e la console mostra "The banner styles were blocked by the Content-Security-Policy…"La CSP blocca gli stili del banner, di solito su Safari prima della 16.4Metti il nonce sullo snippet o nel tag <meta name="csp-nonce">, come in Stili del banner
Con script-src 'nonce-…' il banner non compareLo snippet non ha il nonceAggiungi il nonce del sito allo snippet, come in Script con nonce
Con script-src 'nonce-…' uno script marcato resta bloccato dopo il consensoLo script marcato non ha il nonceAggiungi il nonce del sito al tag dello script
L'archivio consensi non riceve i consensi del banner, anche se il visitatore sceglieLa CSP blocca l'invio verso api.avacy.eu. Il banner salva la scelta nel browser e non mostra errori. La console del browser mostra un errore della Content Security PolicyAggiungi https://api.avacy.eu a connect-src

Ultimo aggiornamento: 10/11/2026.