Documentazione Tracking ed Eventi

Tutto ciò che serve per installare ClearAnalytics sul tuo sito web e tracciare visualizzazioni di pagina, eventi personalizzati, obiettivi di clic e transazioni e-commerce.

Panoramica

ClearAnalytics offre due varianti di script di tracking. Scegli quella più adatta alle tue esigenze: uno script minimale per le analytics di base delle visualizzazioni di pagina, o uno script completo per eventi personalizzati, obiettivi di clic e tracciamento e-commerce.

Light Script (ca.js)

Lo script di tracking più leggero possibile. Perfetto per blog, landing page e siti che necessitano solo di analytics delle visualizzazioni di pagina.

ca.js < 1 KB

Tracciamento automatico delle visualizzazioni di pagina
Durata della sessione e frequenza di rimbalzo
Acquisizione dei parametri di campagna UTM
Supporto per applicazioni a pagina singola

Full Script (ca-events.js)

Tutto ciò che è nel light script, più eventi personalizzati, tracciamento degli obiettivi di clic, intercettazione del dataLayer GA4 e supporto e-commerce completo.

ca-events.js < 2 KB

Tutto ciò che è nel light script
Tracciamento eventi personalizzati tramite window.ca()
Tracciamento obiettivi di clic tramite data-ca-goal
Integrazione dataLayer GA4
Tracciamento completo degli eventi e-commerce

Installazione

Aggiungi un singolo tag script al tuo sito web. Nessun pacchetto npm, nessuno strumento di build, nessun file di configurazione. Lo script si carica in modo asincrono e non ha alcun impatto sulle prestazioni della pagina.

HTML — Light Script

Aggiungi questo nell'<head> o alla fine del <body> in ogni pagina. Traccia automaticamente le visualizzazioni di pagina, la durata della sessione e i parametri UTM.

<script defer src="https://clearanalytics.eu/js/ca.js"></script>

HTML — Full Script

Usa questa variante se hai bisogno di eventi personalizzati, obiettivi di clic o tracciamento e-commerce.

<script defer src="https://clearanalytics.eu/js/ca-events.js"></script>

HTML — Full Script con DataLayer

Aggiungi l'attributo data-ca-datalayer per intercettare automaticamente gli eventi del dataLayer GA4, inclusi tutti gli eventi e-commerce.

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

WordPress

Aggiungi il tag script tramite il file functions.php del tuo tema o usa un plugin di iniezione header/footer.

// functions.php
add_action('wp_head', function () {
    echo '<script defer src="https://clearanalytics.eu/js/ca-events.js"></script>';
});

React / Next.js

Usa il componente Script di Next.js per un caricamento ottimale. Lo script funziona con qualsiasi framework React.

// app/layout.tsx  (Next.js App Router)
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <head>
        <Script
          src="https://clearanalytics.eu/js/ca-events.js"
          strategy="afterInteractive"
        />
      </head>
      <body>{children}</body>
    </html>
  );
}

Vue / Nuxt

Aggiungi lo script tramite la configurazione di Nuxt o direttamente nel tuo template HTML per le app Vue semplici.

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://clearanalytics.eu/js/ca-events.js',
          defer: true,
        },
      ],
    },
  },
});

Google Tag Manager

Puoi anche distribuire lo script tramite Google Tag Manager usando un tag HTML personalizzato.

Tag Type:   Custom HTML
Trigger:    All Pages

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Quando usi GTM con l'attributo data-ca-datalayer, ClearAnalytics catturerà automaticamente tutti gli eventi dataLayer inviati dai tuoi tag GTM esistenti.

Eventi Personalizzati

Traccia qualsiasi interazione utente inviando eventi personalizzati con metadati opzionali. Gli eventi personalizzati appaiono nella tua dashboard e possono essere usati come trigger degli obiettivi.

Richiede il full script (ca-events.js).

API Signature

window.ca(eventName, properties?);

Parametro	Tipo	Descrizione
`eventName`	string	Un nome descrittivo per l'evento (es. 'signup', 'file_download').
`properties`	object	Oggetto opzionale con metadati aggiuntivi. Serializzato come JSON.

Esempi

// Tracciare una registrazione con info sul piano

window.ca('signup', { plan: 'pro' });

// Tracciare il download di un file

window.ca('file_download', {
  file_name: 'whitepaper.pdf',
  file_type: 'pdf',
});

// Tracciare la riproduzione di un video

window.ca('video_play', {
  video_title: 'Product Demo',
  duration: 120,
});

// Tracciare una ricerca interna

window.ca('search', { query: 'privacy analytics' });

Tracciamento Obiettivi di Clic

Traccia i clic su pulsanti e link senza scrivere JavaScript. Aggiungi un attributo data-ca-goal a qualsiasi elemento HTML e il clic verrà registrato automaticamente.

Richiede il full script (ca-events.js).

Utilizzo

Aggiungi data-ca-goal="goal-name" a qualsiasi elemento cliccabile. Il valore dell'attributo diventa l'identificatore dell'obiettivo nella tua dashboard.

<button data-ca-goal="cta-signup">Sign Up</button>

<a href="/pricing" data-ca-goal="pricing-click">View Pricing</a>

<form data-ca-goal="contact-form-submit">
  <!-- The goal fires when any element inside is clicked -->
  <button type="submit">Send</button>
</form>

Come funziona

Lo script usa la delega degli eventi sul documento per rilevare i clic in modo efficiente:

Un evento di clic viene attivato ovunque sulla pagina.
Lo script risale l'albero DOM dall'elemento cliccato cercando un attributo data-ca-goal.
Se trovato, invia un evento di clic con il nome dell'obiettivo come selettore.

Visualizzare gli Obiettivi di Clic

Gli eventi degli obiettivi di clic appaiono nella pagina Obiettivi della tua dashboard. Crea un obiettivo di tipo "Clic" e associalo al valore data-ca-goal che hai usato nel tuo HTML.

Integrazione DataLayer GA4

Se il tuo sito invia già eventi al dataLayer di Google Analytics, ClearAnalytics può intercettare quegli eventi automaticamente. Questo è il percorso di migrazione più semplice da GA4.

Richiede il full script (ca-events.js).

Abilitare l'intercettazione del DataLayer

Aggiungi l'attributo data-ca-datalayer al tag script. Questo approccio opt-in garantisce che la funzionalità si attivi solo quando la abiliti esplicitamente.

<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Come funziona

Quando abilitato, lo script intercetta tutte le chiamate dataLayer.push():

Gli eventi e-commerce riconosciuti (purchase, add_to_cart, ecc.) vengono inoltrati come eventi e-commerce.
Tutti gli altri eventi personalizzati vengono inoltrati come eventi personalizzati generici.
Gli eventi interni di GTM (gtm.js, gtm.dom, gtm.load, ecc.) vengono filtrati automaticamente.
Le voci dataLayer esistenti vengono elaborate al caricamento della pagina; i push futuri vengono intercettati in tempo reale.

Esempio

// These dataLayer pushes are automatically captured
dataLayer.push({
  event: 'form_submit',
  form_id: 'contact',
  form_name: 'Contact Form',
});

dataLayer.push({
  event: 'video_start',
  video_title: 'Product Demo',
  video_duration: 120,
});

Eventi ignorati

I seguenti eventi interni di GTM vengono automaticamente ignorati e non appariranno nella tua dashboard:

// These GTM internal events are automatically filtered out:
gtm.js, gtm.dom, gtm.load, gtm.click, gtm.linkClick, gtm.scrollDepth

Tracciamento E-Commerce

Traccia l'intero percorso del cliente dalla navigazione dei prodotti all'acquisto e al rimborso. ClearAnalytics supporta tutti i 14 eventi e-commerce standard usando lo stesso formato dataLayer di GA4.

Richiede il full script (ca-events.js) con l'attributo data-ca-datalayer.

Tutti gli eventi e-commerce usano il formato dataLayer.push() compatibile con GA4. Se hai già implementato il tracciamento e-commerce di GA4, ClearAnalytics catturerà quegli eventi automaticamente senza modifiche al codice.

Evento	Descrizione
`view_item_list`	L'utente visualizza un elenco di prodotti o risultati di ricerca.
`select_item`	L'utente clicca su un prodotto in un elenco.
`view_item`	L'utente visualizza una pagina di dettaglio prodotto.
`add_to_cart`	L'utente aggiunge un prodotto al carrello.
`remove_from_cart`	L'utente rimuove un prodotto dal carrello.
`view_cart`	L'utente visualizza il carrello.
`add_to_wishlist`	L'utente aggiunge un prodotto alla lista dei desideri.
`begin_checkout`	L'utente avvia il processo di checkout.
`add_shipping_info`	L'utente invia le informazioni di spedizione.
`add_payment_info`	L'utente invia le informazioni di pagamento.
`purchase`	L'utente completa un acquisto.
`refund`	Viene elaborato un rimborso totale o parziale.
`view_promotion`	L'utente visualizza un banner promozionale o un'offerta.
`select_promotion`	L'utente clicca su una promozione.

view_item_list

Attiva questo evento quando gli utenti vedono un elenco di prodotti, come una pagina di categoria o risultati di ricerca.

dataLayer.push({ ecommerce: null }); // Clear previous data
dataLayer.push({
  event: 'view_item_list',
  ecommerce: {
    item_list_id: 'category_results',
    item_list_name: 'Category Results',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Running Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        price: 89.99,
        index: 0,
      },
      {
        item_id: 'SKU-002',
        item_name: 'Trail Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        price: 119.99,
        index: 1,
      },
    ],
  },
});

select_item

Attiva questo evento quando un utente clicca su un prodotto specifico in un elenco per visualizzarlo.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'select_item',
  ecommerce: {
    item_list_id: 'category_results',
    item_list_name: 'Category Results',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      price: 89.99,
      index: 0,
    }],
  },
});

view_item

Attiva questo evento quando un utente arriva su una pagina di dettaglio prodotto.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_item',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      item_category: 'Footwear',
      item_variant: 'Blue / Size 42',
      price: 89.99,
      quantity: 1,
    }],
  },
});

add_to_cart

Attiva questo evento quando un utente aggiunge uno o più prodotti al carrello.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      item_brand: 'SportCo',
      price: 89.99,
      quantity: 1,
    }],
  },
});

remove_from_cart

Attiva questo evento quando un utente rimuove un prodotto dal carrello.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'remove_from_cart',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
      quantity: 1,
    }],
  },
});

view_cart

Attiva questo evento quando un utente visualizza la pagina del carrello.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_cart',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_to_wishlist

Attiva questo evento quando un utente salva un prodotto nella lista dei desideri per dopo.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_to_wishlist',
  ecommerce: {
    currency: 'EUR',
    value: 89.99,
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
    }],
  },
});

begin_checkout

Attiva questo evento quando un utente avvia il flusso di checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'begin_checkout',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    coupon: 'SUMMER20',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_shipping_info

Attiva questo evento quando un utente seleziona o invia i dettagli di spedizione durante il checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_shipping_info',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    shipping_tier: 'Express',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

add_payment_info

Attiva questo evento quando un utente seleziona o invia il metodo di pagamento durante il checkout.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'add_payment_info',
  ecommerce: {
    currency: 'EUR',
    value: 209.98,
    payment_type: 'Credit Card',
    items: [
      { item_id: 'SKU-001', item_name: 'Running Shoes', price: 89.99, quantity: 1 },
      { item_id: 'SKU-003', item_name: 'Sports Watch', price: 119.99, quantity: 1 },
    ],
  },
});

purchase

Attiva questo evento quando un acquisto viene confermato. Includi transaction_id, value, currency, tax, shipping e l'array completo degli items.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
    affiliation: 'Online Store',
    value: 209.98,
    tax: 36.49,
    shipping: 5.99,
    currency: 'EUR',
    coupon: 'SUMMER20',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Running Shoes',
        item_brand: 'SportCo',
        item_category: 'Footwear',
        item_variant: 'Blue / Size 42',
        price: 89.99,
        quantity: 1,
        coupon: '',
      },
      {
        item_id: 'SKU-003',
        item_name: 'Sports Watch',
        item_brand: 'FitTech',
        item_category: 'Electronics',
        item_variant: 'Black',
        price: 119.99,
        quantity: 1,
        coupon: '',
      },
    ],
  },
});

refund

Attiva questo evento quando viene elaborato un rimborso. Per un rimborso totale, è richiesto solo il transaction_id. Per rimborsi parziali, includi gli articoli specifici.

// Full refund
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'refund',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
  },
});

// Partial refund (specific items)
dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'refund',
  ecommerce: {
    transaction_id: 'TXN-20260219-001',
    items: [{
      item_id: 'SKU-001',
      quantity: 1,
    }],
  },
});

view_promotion

Attiva questo evento quando un banner promozionale, carosello o offerta diventa visibile all'utente.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'view_promotion',
  ecommerce: {
    creative_name: 'Spring Banner',
    creative_slot: 'homepage_hero',
    promotion_id: 'PROMO-SPRING-2026',
    promotion_name: 'Spring Sale 2026',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
      discount: 15.00,
    }],
  },
});

select_promotion

Attiva questo evento quando un utente clicca su una promozione per saperne di più o approfittare dell'offerta.

dataLayer.push({ ecommerce: null });
dataLayer.push({
  event: 'select_promotion',
  ecommerce: {
    creative_name: 'Spring Banner',
    creative_slot: 'homepage_hero',
    promotion_id: 'PROMO-SPRING-2026',
    promotion_name: 'Spring Sale 2026',
    items: [{
      item_id: 'SKU-001',
      item_name: 'Running Shoes',
      price: 89.99,
    }],
  },
});

Migrazione da Google Analytics

ClearAnalytics è progettato per funzionare insieme a o in sostituzione di Google Analytics. Puoi eseguire entrambi gli strumenti in parallelo durante la migrazione senza conflitti.

Eseguire entrambi gli script in parallelo

Aggiungi lo script di ClearAnalytics accanto al tuo tag Google Analytics esistente. Entrambi gli script tracciano in modo indipendente senza interferire tra loro.

<!-- Google Analytics (existing) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXX');
</script>

<!-- ClearAnalytics (add this line) -->
<script defer src="https://clearanalytics.eu/js/ca-events.js" data-ca-datalayer></script>

Compatibilità delle funzionalità

Ecco come le funzionalità di ClearAnalytics corrispondono ai loro equivalenti di Google Analytics:

Funzionalità	Google Analytics	ClearAnalytics
Visualizzazioni di pagina	`gtag('event', 'page_view')`	Automatico
Eventi Personalizzati	`gtag('event', ...)`	`window.ca('event')`
E-Commerce	`dataLayer.push()`	Compatibile con dataLayer
Campagne UTM	Automatico	Automatico
Sessioni	Basato su cookie	Senza cookie

Passaggi di migrazione

Aggiungi lo script di ClearAnalytics al tuo sito accanto a Google Analytics.
Abilita l'intercettazione del dataLayer con data-ca-datalayer per catturare gli eventi e-commerce esistenti.
Confronta i dati in entrambe le dashboard per 2-4 settimane per verificare l'accuratezza.
Una volta soddisfatto, rimuovi lo script di Google Analytics e goditi una configurazione più veloce e orientata alla privacy.

Supporto SPA

ClearAnalytics rileva automaticamente la navigazione lato client nelle applicazioni a pagina singola. Non è richiesta alcuna configurazione aggiuntiva o integrazione con il router.

Come funziona

Lo script intercetta le chiamate alla History API del browser per rilevare la navigazione di pagina:

history.pushState() le chiamate vengono intercettate e attivano una nuova visualizzazione di pagina.
history.replaceState() le chiamate vengono intercettate e attivano una nuova visualizzazione di pagina.
popstate gli eventi (indietro/avanti del browser) attivano una nuova visualizzazione di pagina.

Framework compatibili

Funziona immediatamente con qualsiasi framework che usa la History API per il routing:

React Next.js Vue.js Nuxt Svelte SvelteKit Angular Remix Astro Inertia.js

Non servono plugin per il router, hook del ciclo di vita o chiamate di tracciamento manuali. Basta aggiungere il tag script una volta e ogni navigazione di pagina viene tracciata automaticamente.

Privacy e Conformità

ClearAnalytics è costruito con la privacy al centro. Lo script di tracking raccoglie solo dati anonimi e aggregati. Nessuna informazione personale viene mai memorizzata o trasmessa.

Nessun cookie

Lo script non imposta, legge o dipende da cookie del browser. Non è necessario alcun banner di consenso ai cookie.

Nessun fingerprinting

Non creiamo mai impronte digitali del browser. Non vengono utilizzate tecniche di fingerprinting canvas, WebGL, font o audio.

Nessuna memorizzazione IP

Gli indirizzi IP dei visitatori vengono utilizzati solo per l'hashing anonimizzato durante la richiesta. Non vengono mai memorizzati nel database.

Conforme al GDPR

Poiché non vengono raccolti dati personali, ClearAnalytics è al di fuori dell'ambito dei requisiti di consenso del GDPR. Tutti i dati rimangono nell'UE.

Come anonimizziamo i visitatori

Per contare i visitatori unici senza memorizzare dati personali, utilizziamo un hash anonimo a rotazione giornaliera:

L'indirizzo IP e lo User-Agent del visitatore vengono combinati con un salt a rotazione giornaliera.
Questa combinazione viene sottoposta a hash usando un algoritmo SHA-256 unidirezionale.
Il salt ruota ogni 24 ore, rendendo impossibile tracciare i visitatori tra giorni diversi.
L'indirizzo IP originale non viene mai memorizzato o registrato.

Dati raccolti dallo script

I seguenti campi di dati non personali vengono inviati con ogni evento di visualizzazione di pagina:

Campo	Scopo
`pathname`	Il percorso URL della pagina visitata.
`referrer`	L'URL della pagina di provenienza, se presente.
`language`	L'impostazione della lingua del browser.
`screen_width / screen_height`	Dimensioni dello schermo per la classificazione del tipo di dispositivo.
`utm_*`	Parametri di tracciamento campagna dall'URL.
`duration`	Tempo trascorso sulla pagina in secondi.

Poiché ClearAnalytics non raccoglie mai dati personali, non hai bisogno di un banner di consenso ai cookie, popup sulla privacy o meccanismo di opt-in per usare il nostro script di tracking. È conforme a GDPR, ePrivacy, PECR e CCPA fin da subito.