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
-
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.

-
Apri la scheda Integra Avacy, poi la voce Codice HTML.
-
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 dopowebspace=è l'identificativo del tuo spazio web. Copia lo snippet così com'è. Questi valori di esempio compaiono in tutta la documentazione. -
Apri il file che contiene il
<head>delle pagine. Con un tema o un template, apri il<head>condiviso da tutte le pagine. -
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> -
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
dataLayeril 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.
| Indirizzo | A cosa serve | Direttiva |
|---|---|---|
https://<team>.avacy-cdn.com | Loader, codice del banner e componenti aggiuntivi del banner (file .js). Non serve se script-src usa il nonce, vedi Script con nonce | script-src |
https://<team>.avacy-cdn.com | Configurazione dello spazio web, traduzioni delle lingue che il banner non include | connect-src |
https://<team>.avacy-cdn.com | Immagini del banner, come l'icona delle preferenze | img-src |
https://assets.avacy-cdn.com | Elenchi dei fornitori TCF e dei fornitori Google, solo con quei framework attivi | connect-src |
https://assets.avacy-cdn.com | Logo caricato dalla dashboard | img-src |
https://api.avacy.eu | Invio dei consensi all'archivio consensi, solo se l'archiviazione automatica è attiva | connect-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
| Sintomo | Causa probabile | Cosa fare |
|---|---|---|
| Il banner non compare | Lo spazio web non ha il banner pubblicato, oppure lo snippet usa un codice sbagliato | Controlla la console come in Verificare che il banner funzioni |
| L'avviso "Google tags ran before…" compare nella console | Un tag Google parte prima dello snippet | Sposta lo snippet sopra i tag Google |
| Il banner compare solo su alcune pagine | Lo snippet è in un file che non tutte le pagine usano | Incolla lo snippet nel file del <head> condiviso |
La console mostra errori di rete verso avacy-cdn.com | La CSP del sito blocca l'indirizzo | Autorizza 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 TCF | Aggiungi 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.4 | Metti il nonce sullo snippet o nel tag <meta name="csp-nonce">, come in Stili del banner |
Con script-src 'nonce-…' il banner non compare | Lo snippet non ha il nonce | Aggiungi il nonce del sito allo snippet, come in Script con nonce |
Con script-src 'nonce-…' uno script marcato resta bloccato dopo il consenso | Lo script marcato non ha il nonce | Aggiungi il nonce del sito al tag dello script |
| L'archivio consensi non riceve i consensi del banner, anche se il visitatore sceglie | La 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 Policy | Aggiungi https://api.avacy.eu a connect-src |
Ultimo aggiornamento: 10/11/2026.