Integrare Analytics Rispettosi della Privacy in un Sito Astro
Le View Transitions di Astro rompono silenziosamente gli script di analytics standard. Ecco il pattern corretto per tracciare ogni cambio di route senza cookie né banner di consenso.
Le View Transitions di Astro scambiano il contenuto della pagina senza un ricaricamento completo del browser — il che significa che qualsiasi script di analytics che si basa su DOMContentLoaded o load si attiverà una sola volta, alla visita iniziale. Ogni navigazione lato client successiva è invisibile. Non è un errore di configurazione da parte tua; è una conseguenza fondamentale del funzionamento del ClientRouter.
Lo stesso problema di tracciamento silenzioso esiste in SvelteKit 2 e Remix, ma la soluzione è diversa per ciascun framework. In Astro, la risposta è l'evento di ciclo di vita astro:page-load.
Perché il consueto tag script fallisce
Quando <ClientRouter /> è attivo (opt-in tramite astro:transitions in Astro 4, abilitato di default in Astro 5), le navigazioni non scaricano la pagina. Astro recupera la pagina successiva in background, scambia il DOM e aggiorna l'URL — tutto senza distruggere il contesto JavaScript corrente.
Uno script di tracking caricato tramite un semplice tag <script> viene trattato come uno script di modulo bundled dalla pipeline di build di Astro. Gli script di modulo bundled vengono eseguiti esattamente una volta per sessione di pagina. Il tracker si inizializza, registra un pageview per la landing page, e poi non viene più eseguito mentre l'utente naviga.
Per attivarsi a ogni navigazione, la logica di inizializzazione deve essere collegata al ciclo di vita di navigazione di Astro. L'hook giusto è astro:page-load, che si attiva dopo che la nuova pagina è visibile e tutti gli script bloccanti sono caricati — sia al caricamento iniziale sia a ogni transizione successiva.
L'integrazione corretta
Aggiungi lo script di tracking una sola volta nel tuo layout principale (src/layouts/Layout.astro o equivalente), poi collega un listener per astro:page-load:
---
// Layout.astro
---
<html lang="it">
<head>
<!-- contenuto dell'head -->
</head>
<body>
<slot />
<script
is:inline
src="https://api.monoid.website/tracker.min.js"
data-site-id="YOUR_SITE_ID"
async
></script>
</body>
</html>
La direttiva is:inline dice al bundler di Astro di lasciare questo script esattamente com'è. Senza di essa, Astro tratterebbe lo script come un modulo, lo deduplicherebbe e sopprimerebbe la ri-esecuzione. Con is:inline, il tag script viene emesso letteralmente nell'HTML di ogni pagina.
Per i siti che non usano View Transitions, questo è tutto ciò che serve. Il tracker si attiva una volta al caricamento e hai finito.
Gestire la navigazione con View Transitions
Se il tuo sito usa <ClientRouter />, non è richiesta alcuna configurazione aggiuntiva — ma vale la pena essere precisi sul perché, perché la spiegazione abituale è sbagliata.
Il tracker non ascolta astro:page-load né alcun altro evento del ciclo di vita di Astro. Applica una patch a history.pushState quando viene caricato. Il router di Astro aggiorna l'URL tramite quella stessa chiamata alla History API, quindi la funzione patchata viene eseguita a ogni transizione e invia un pageview. L'hook si colloca sotto il livello di eventi di Astro invece di ascoltarlo.
Per verificare, apri la scheda Network di DevTools e filtra per collect. Naviga tra due pagine. Dovresti vedere una richiesta POST per navigazione, inclusa quella iniziale.
Un avvertimento da conoscere: l'hook copre pushState, non popstate. Premere Indietro o Avanti cambia la rotta senza chiamare pushState, quindi attualmente non produce un nuovo pageview.
Il tracker non espone alcun metodo manuale di pageview. Il global accetta solo eventi personalizzati:
<script>
// Solo eventi personalizzati — non esiste una chiamata trackPageview().
// Il nome deve corrispondere a [a-z0-9_][a-z0-9_-]{0,63}.
window.monoid('event', 'signup_started');
</script>
Separare gli ambienti
I progetti Astro hanno tipicamente ambienti di sviluppo locale, preview e produzione. Usa una variabile d'ambiente per memorizzare il site_id e sopprimere il tracking in sviluppo:
---
const siteId = import.meta.env.PUBLIC_MONOID_SITE_ID
---
{siteId && (
<script
is:inline
src="https://api.monoid.website/tracker.min.js"
data-site-id={siteId}
async
></script>
)}
Imposta PUBLIC_MONOID_SITE_ID in .env per la produzione e lasciala non definita in locale. Astro espone al client le variabili con prefisso PUBLIC_; le variabili solo server (senza il prefisso) non sono visibili nel codice eseguito nel browser.
Cosa non ti serve
Nessun banner di consenso per i cookie. Nessuna integrazione con una CMP. L'endpoint di raccolta calcola un hash giornaliero del visitatore a partire dall'indirizzo IP, dallo User-Agent, da un segreto lato server e dalla data corrente:
visitor_hash = SHA-256(IP + UA + SALT_SECRET + YYYY-MM-DD)
L'hash si reimposta ogni 24 ore. Nulla viene memorizzato sul dispositivo del visitatore. La famiglia di browser e il tipo di dispositivo vengono derivati lato server dallo User-Agent della richiesta per il reporting aggregato — le stringhe User-Agent complete, le versioni del browser e gli identificatori persistenti non vengono mai memorizzati.
I siti Astro sono spesso completamente statici o renderizzati all'edge con JavaScript minimo. Aggiungere uno script di analytics sotto i 2 KB senza cookie e senza obbligo di consenso si inserisce naturalmente in questa filosofia. Non c'è alcun pacchetto npm da mantenere, nessun SDK da aggiornare e nessuna base giuridica GDPR da documentare per il trattamento di analytics.
Comments
Loading comments…