Lo snippet di tracciamento è un piccolo script asincrono — pochi kilobyte serviti da un percorso di prima parte memorizzato nella cache edge — che identifica l'organizzazione dietro ogni sessione. Se installato correttamente, non lo noterai mai. Se installato in modo errato, passerai una settimana a fare debugging per capire perché mancano le aziende identificate, prima di scoprire che il loader era all'interno di un partial caricato in modalità lazy-load. Questa guida ti farà risparmiare quella settimana.
Tre principi prima di incollare qualsiasi cosa
- Il loader deve stare nell'HTML head globale del sito. Non nel footer, non in un template di pagina specifico, non in un componente che viene visualizzato solo sulle pagine di marketing. Nell'head, su ogni pagina.
- Il loader è asincrono per impostazione predefinita. Non aggiungere override defer/async che ne cambino l'esecuzione; gli attributi forniti sono quelli testati.
- Installa una sola volta, esattamente. Due copie del loader sulla stessa pagina non raddoppiano i dati: raddoppiano le richieste e confondono il debugging.
WordPress
L'installazione più pulita su WordPress evita modifiche al tema. Usa un plugin per header-scripts (uno qualsiasi dei più noti andrà bene), incolla il loader nel campo "script nell'head", salva e svuota la cache delle pagine. Se non vuoi un plugin, aggiungi un piccolo file mu-plugin che si agganci a wp_head con priorità 5, in modo che il loader arrivi prima dei tag di analytics. Non incollarlo nel corpo di una pagina o di un post: WordPress filtrerebbe il tag script per sicurezza.
Un controllo specifico per WordPress: se utilizzi una cache a pagina intera (LiteSpeed, WP Rocket, W3 Total Cache), svuota la cache dopo l'installazione. L'HTML memorizzato nella cache che precede l'installazione non conterrà il loader.
Shopify
Shopify inserisce l'HTML del tema in theme.liquid. Nel pannello di controllo Shopify, vai su Negozio Online → Temi → Azioni → Modifica codice → theme.liquid e incolla il loader immediatamente prima del tag di chiusura </head>. Salva. Tutto qui — non è necessaria alcuna app, né script di checkout (il checkout è comunque fuori ambito per l'identificazione a livello aziendale).
Duplica prima il tema
Prima di modificare theme.liquid, usa Azioni → Duplica. Se qualcosa dovesse andare storto, potrai ripristinare il tutto con un clic. È un'abitudine di cinque secondi che ha salvato ogni team Shopify a cui è stata suggerita.
Webflow
Webflow → Impostazioni sito → Codice personalizzato → Codice head. Incolla il loader. Salva. Pubblica il sito. Il codice dell'head viene applicato globalmente a tutte le pagine, che è esattamente ciò che desideri. Non incollare il loader in un embed a livello di singola pagina: tracceresti solo quella pagina.
Google Tag Manager
GTM funziona, con due accortezze. Primo, usa un tag HTML personalizzato con l'attivatore impostato su "Tutte le pagine" in modo che il loader venga eseguito su ogni visualizzazione di pagina. Secondo, imposta la priorità del tag abbastanza alta da farlo scattare prima di altri tag di analytics che potrebbero rallentare il payload iniziale. Gli utenti GTM spesso stratificano quattro o cinque tag nell'head; il loader è piccolo, ma l'ordine di attivazione dei tag conta se desideri l'identificazione fin dalla prima richiesta.
Nota sulla modalità di consenso: se utilizzi GTM dietro un banner di consenso che attiva i tag di analytics solo dopo l'accettazione, non mettere l'identificazione a livello aziendale dietro lo stesso blocco — non utilizza cookie né memorizza dati sul dispositivo del visitatore, quindi non richiede lo stesso consenso. Configura il tag affinché si attivi immediatamente, insieme ai tag strettamente necessari.
HTML puro / stack personalizzati
Per un sito scritto a mano o un framework non menzionato, incolla il loader all'interno dell'elemento <head> del tuo template di base — il file che viene renderizzato su ogni pagina. Ricostruisci e distribuisci. Per i generatori di siti statici, il loader va nel file di layout globale (in Next.js, è uno <Script> nel layout a livello di app con strategy="afterInteractive"; in Astro, il componente <BaseHead>; in 11ty, il partial del template base). Se lo aggiungi come script a livello di componente, verranno tracciate solo le pagine che includono quel componente.
Single-page applications — l'insidia
In una SPA, la visualizzazione della pagina iniziale viene catturata dal loader al primo caricamento. Le successive navigazioni lato client non sono visualizzazioni di pagina automatiche dal punto di vista del browser. Il nostro loader ascolta la History API per impostazione predefinita, quindi le navigazioni avanti/indietro e quelle basate su pushState vengono registrate come nuove visualizzazioni di pagina senza alcun codice aggiuntivo. Se la tua SPA utilizza un router non standard che bypassa la History API (raro, ma possibile), chiama la piccola funzione pageview documentata al cambio di rotta: tre righe, citate nella documentazione.
Verifica l'installazione in due minuti
La verifica non è facoltativa. Fallo prima di chiudere la scheda con cui hai installato il loader; correggere un'installazione errata cinque minuti dopo aver incollato il codice è banale, farlo cinque giorni dopo no.
- Apri il tuo sito in una finestra privata/incognito (così le risorse memorizzate nella cache non ti confonderanno).
- Apri DevTools → scheda Network, filtra per "l5e" o per il percorso del loader.
- Ricarica la pagina. Dovresti vedere una richiesta al loader, seguita da un piccolo beacon identificativo. Entrambi dovrebbero avere come stato 200. Gli header di risposta del loader dovrebbero includere un cache-control con s-maxage e stale-while-revalidate.
- Naviga su una seconda pagina. Dovresti vedere scattare un secondo beacon identificativo, senza scaricare nuovamente il loader (darà un 304).
- Torna alla dashboard di lead.box, apri il feed dei visitatori in tempo reale e conferma che la tua visita di prova appaia. Se appare, l'installazione è completata.
Errori comuni — la tabella da controllare per prima
| Sintomo | Causa probabile | Soluzione |
|---|---|---|
| Nessuna visita in tempo reale | Loader mancante nell'head, o sul template sbagliato | Sposta il loader nel template head globale del sito |
| Visite solo da una sezione | Loader in un embed di pagina, non globale | Sposta nell'head globale / header del tema |
| Il loader si carica ma nessun beacon | Banner del consenso che blocca script di terze parti aggressivamente | Configura il banner per consentire gli script necessari; il loader non richiede consenso |
| Doppio beacon per pagina | Loader installato due volte (tema + plugin/tag) | Rimuovine uno |
| Primo caricamento lento dopo installazione | Loader posizionato prima del CSS critico | Conferma la presenza dell'attributo async; posizionalo dopo il preload del CSS critico |
| La SPA riporta solo la prima pagina | Il router personalizzato bypassa la History API | Chiama la funzione pageview() documentata al cambio di rotta |
| HTML vecchio servito senza loader | Cache a pagina intera non svuotata dopo l'installazione | Svuota la cache; verifica in modalità incognito |
Nota sulle prestazioni — loader edge-cached
Il loader viene servito da un percorso di prima parte proxyato alla nostra cache edge con s-maxage=300 e stale-while-revalidate. In pratica, questo significa che il loader viene recuperato una volta ogni cinque minuti per ogni PoP edge, quindi servito dalla cache a ogni visitatore successivo. Il peso in byte e l'impatto sul blocco sono così ridotti che non consigliamo di aggiungere logiche di caricamento supplementari.
Quando chiedere aiuto
Se hai seguito i passaggi di verifica e qualcosa non va ancora per il verso giusto, preferiamo sentirti dopo dieci minuti piuttosto che dopo dieci giorni. Porta con te tre cose: l'URL del sito, uno screenshot della scheda Network di DevTools filtrata per il percorso del loader e il nome della piattaforma su cui lo hai installato. Questo è sufficiente per diagnosticare quasi ogni problema di installazione alla prima risposta.
Pubblicato da
lead.box Team
Altri articoli
Veda lead.box in azione sul Suo traffico
Inizi gratuitamente — nessuna carta, nessuna chiamata di vendita richiesta. Oppure prenoti una panoramica di 20 minuti per un tour guidato.