Aggiungere Analytics Rispettosi della Privacy a un'App SvelteKit

SvelteKit 2 ha rotto silenziosamente la maggior parte delle integrazioni di analytics esistenti. Un semplice tag <script> che funzionava bene in SvelteKit 1 si attiverà solo nei ricaricamenti hard in SvelteKit 2, mancando ogni navigazione lato client. Anche la soluzione standard — agganciarsi a history.pushState — non funziona, perché SvelteKit intercetta la navigazione a livello di router prima che pushState venga chiamato. Il tracker di Monoid gestisce correttamente questo caso fin dall'inizio.

Perché l'approccio consueto fallisce

Gli script di analytics tradizionali rilevano i cambi di route tramite monkey-patching di history.pushState e history.replaceState. Il router di SvelteKit chiama le proprie primitive di navigazione interne e chiama pushState solo come effetto collaterale, dopo che la transizione di route è già in corso. Quando il pushState patchato si attiva, la nuova route potrebbe non essere ancora completamente renderizzata, e in alcuni tipi di navigazione (chiamate programmatiche a goto(), click su <a> con preloading) il timing produce duplicati o eventi mancati.

Questa è la causa principale del problema ampiamente segnalato in cui Google Analytics GA4 registra solo il primo pageview al caricamento iniziale nelle applicazioni SvelteKit 2.

L'approccio corretto

Aggiungi lo script tracker di Monoid una sola volta al tuo +layout.svelte principale usando <svelte:head>:

<svelte:head>
  <script
    async
    src="https://api.monoid.website/tracker.min.js"
    data-site-id="YOUR_SITE_ID"
  ></script>
</svelte:head>

Il listener DOMContentLoaded integrato nel tracker si attiva al caricamento iniziale della pagina. Per le navigazioni lato client successive, l'hook history.pushState del tracker si attiva dopo che la navigazione interna di SvelteKit è stata risolta — il che significa che ogni route, inclusa la prima, viene tracciata esattamente una volta senza duplicati né eventi mancati.

Per verificare, apri la scheda Network in DevTools e osserva le richieste POST verso /collect. Dovresti vederne una per ogni cambio di route.

Separare il traffico di staging

I progetti SvelteKit tipicamente girano su localhost durante lo sviluppo. Registra un sito separato e associa il suo site_id a una variabile d'ambiente in modo che il traffico di sviluppo non inquini mai le metriche di produzione:

<script>
  const siteId = import.meta.env.VITE_MONOID_SITE_ID
</script>

<svelte:head>
  {#if siteId}
    <script
      async
      src="https://api.monoid.website/tracker.min.js"
      data-site-id={siteId}
    ></script>
  {/if}
</svelte:head>

Imposta VITE_MONOID_SITE_ID in .env.local per lo sviluppo (oppure lasciala non impostata per sopprimere il tracking) e nel tuo ambiente di deployment per la produzione. Il blocco {#if siteId} garantisce che il tracker non venga mai iniettato quando la variabile non è impostata.

Cosa non ti serve

Nessun banner di consenso per i cookie. Nessun aggiornamento della cookie policy. Nessun controllo navigator.cookieEnabled. L'endpoint di raccolta deriva 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 e non può essere invertito per recuperare l'IP o lo User-Agent. Nulla viene memorizzato sul dispositivo del visitatore. Questo significa che l'integrazione non attiva i requisiti di consenso ePrivacy o PECR — non c'è nulla a cui acconsentire.

Verificare nella dashboard

Dopo il deployment, apri la tua dashboard di analytics e naviga tra diverse route sul tuo sito live. Ogni navigazione dovrebbe produrre una nuova voce pageview con il path corretto. Se vedi solo una voce indipendentemente dalla navigazione, controlla che lo script sia caricato nel layout principale e che VITE_MONOID_SITE_ID sia impostato nell'ambiente di produzione.

L'adapter SvelteKit che usi (Cloudflare, Vercel, Node, statico) non influisce sulla raccolta di analytics, poiché il tracking avviene interamente nel browser dopo l'hydration.