Adding Privacy-First Analytics to an Astro Site

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 />, l'hook history.pushState integrato del tracker si attiva correttamente dopo ogni transizione — il tracker ascolta internamente gli eventi di navigazione di Astro. Non è richiesta alcuna configurazione aggiuntiva.

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.

Se stai iniettando il tracker in modo condizionale e hai bisogno che si reinizializzi dopo ogni scambio (ad esempio, dopo il montaggio di un'isola dinamica), puoi attivare manualmente una ri-esecuzione:

<script data-astro-rerun>
  // Questo blocco viene rieseguito dopo ogni View Transition.
  // Da usare con parsimonia — la maggior parte della logica del tracker non dovrebbe stare qui.
  if (window.__monoid) {
    window.__monoid.trackPageview();
  }
</script>

L'attributo data-astro-rerun forza gli script inline a essere rieseguiti dopo ogni transizione. Nota che implica is:inline, quindi si applica solo agli script non bundled.

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.