Help

Questa guida illustra come installare e utilizzare l’SDK Clickstream di SurveyAnalytica nei progetti web. L’SDK è pubblicato su npm e funziona in qualsiasi ambiente JavaScript, inclusi Vanilla JS, Next.js e React. Per le app mobile, consulta la guida agli SDK Mobile.

Prima di iniziare, completa la configurazione del workflow per ottenere la tua API Key e l’Endpoint URL.

Installazione

Siti Vanilla JS / HTML

Includi il bundle UMD direttamente nella pagina. Non è richiesto alcun passaggio di build.

<script src="https://cdn.jsdelivr.net/npm/@surveyanalytica/clickstream-web/dist/index.umd.js"></script>
<script>
  SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
    endpoint: 'YOUR_ENDPOINT_URL'
  });
</script>

Progetti npm (Next.js, React, ecc.)

npm install @surveyanalytica/clickstream-web

Quindi inizializza una sola volta, nel punto di ingresso della tua app:

import { SAClickstream } from '@surveyanalytica/clickstream-web';

SAClickstream.init('YOUR_WORKFLOW_ID', 'YOUR_API_KEY', {
  endpoint: 'YOUR_ENDPOINT_URL'
});

Per Next.js, chiama init all’interno di un Client Component oppure in _app.js / layout.js. L’SDK è sicuro per il rendering lato server: tutti gli accessi alle API del browser sono protetti internamente.

Tracciamento delle visualizzazioni di pagina

L’SDK traccia automaticamente le visualizzazioni di pagina. Ogni volta che l’URL cambia (inclusa la navigazione single-page tramite la History API), viene inviato un evento page_view con l’URL corrente, il titolo della pagina e il referrer. Non è necessario alcun codice oltre alla chiamata init.

Per inviare una visualizzazione di pagina manualmente:

SAClickstream.page('/checkout', { campaign: 'summer-sale' });

Tracciamento di eventi personalizzati

SAClickstream.track('button_clicked', {
  label: 'Buy Now',
  productId: 'sku-9821',
  price: 49.99
});

I valori delle proprietà possono essere stringhe, numeri, booleani o oggetti annidati. Mantieni i nomi degli eventi brevi e coerenti in tutto il codebase (ad esempio, usa sempre button_clicked anziché mischiare buttonClick e btn_tap).

Prima del login, l’SDK assegna a ogni visitatore un ID anonimo casuale memorizzato in localStorage. Dopo il login, chiama identify con l’ID contatto proveniente dal tuo backend:

// After a successful login
SAClickstream.identify('contact-id-from-your-backend');

Questo invia un evento uid_transition che collega la sessione anonima al contatto conosciuto. Gli eventi registrati prima del login vengono associati al contatto tramite l’ID anonimo memorizzato nella scheda contatto: nessun dato viene perso.

Gestione del consenso

Se il tuo sito utilizza un banner di consenso ai cookie, rispetta la scelta dell’utente:

// User accepted tracking
SAClickstream.setConsent(true);

// User declined tracking
SAClickstream.setConsent(false);

Quando il consenso è impostato su false, il tracciamento si interrompe immediatamente e l’associazione con l’ID anonimo viene cancellata. Non verranno inviati ulteriori eventi finché il consenso non viene nuovamente concesso.

Come vengono inviati gli eventi

L’SDK raggruppa gli eventi e li invia ogni 500 millisecondi, oppure immediatamente quando si accumulano 20 eventi in coda. Le richieste non riuscite vengono ritentate fino a tre volte con ritardi crescenti. Questo mantiene basso l’utilizzo della rete senza perdere eventi durante problemi di connettività temporanei.

Risoluzione dei problemi

Gli eventi non compaiono nel mio workflow

Verifica che il workflow sia nello stato Active.
Controlla la console del browser per eventuali errori di rete sulle richieste verso il tuo endpoint URL.
Verifica che l’API Key corrisponda alla KEY mostrata nel pannello del trigger: copia e incolla invece di digitarla.
Assicurati che init venga chiamato prima di qualsiasi chiamata a track o page.

Vengono registrate visualizzazioni di pagina duplicate

Se chiami SAClickstream.page() manualmente in aggiunta al tracciamento automatico, vedrai due eventi per ogni navigazione. Disattiva il tracciamento automatico (autoPage: false nelle opzioni di init) oppure rimuovi le tue chiamate manuali a page().

We use cookies