SDK Web

Con una sola riga di integrazione, Kixo Web SDK rileva automaticamente clic, visualizzazioni di pagina, sessioni, errori, profondità di scorrimento, web vitals, rage click, dead click e dati per le heatmap. Il monitoraggio delle richieste di rete è disponibile come opzione facoltativa. È distribuito come modulo ES nativo e funziona nei browser moderni.

Installazione

Tag script (CDN)

Aggiungi lo snippet prima del tag di chiusura </head>. Nota type="module": è obbligatorio perché l'SDK è un modulo ES. Il replay di sessione è separato in un chunk del recorder con versione corrispondente, caricato solo dopo l'attivazione del replay; così il bundle di base resta leggero finché il replay è disattivato.

html

<script
  type="module"
  src="https://cdn.kixo.io/kixo.min.js?project_id=YOUR_PROJECT_ID&api_key=YOUR_API_KEY">
</script>

Nota

L’SDK legge project_id e api_key dall’URL dello script e si inizializza automaticamente. Se vuoi configurare le opzioni nel codice dell’applicazione, rimuovi i parametri dall’URL e usa invece Kixo.init({...}): l’oggetto globale Kixo è disponibile non appena il modulo è stato caricato.

html

<script type="module" src="https://cdn.kixo.io/kixo.min.js"></script>
<script type="module">
  Kixo.init({
    projectId: 'YOUR_PROJECT_ID',
    apiKey:    'YOUR_API_KEY',
  });
</script>

npm

Usalo quando vuoi configurare le opzioni nel codice dell’applicazione anziché tramite l’URL dello script. Espone la stessa API Kixo dell’integrazione CDN.

bash

npm install @kixo.io/web

import Kixo from '@kixo.io/web';

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_API_KEY',
});

Piattaforme no-code

Se stai sviluppando con un builder basato su AI come Lovable, Bolt, v0 o Replit, incolla lo snippet del tag script direttamente nella chat del builder o nelle impostazioni di inserimento del codice. La maggior parte dei builder permette di aggiungere script nel <head> del sito.

Configurazione

L’integrazione in due righe usa i valori predefiniti locali di analytics riportati qui sotto. Il monitoraggio delle richieste resta facoltativo. Il session replay è volutamente assente da Kixo.init(): attivazione, campionamento, privacy, durata e impostazioni di acquisizione si gestiscono solo dalla dashboard del progetto.

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',     // required
  apiKey:    'YOUR_API_KEY',         // required

  // Per-tracker toggles — all default to true except network.
  autoTrack: {
    pageViews:   true,
    clicks:      true,
    scrollDepth: true,
    sessions:    true,
    forms:       true,
    network:     false,     // opt in only when you need request telemetry
    errors:      true,
    performance: true,
    rageClicks:  true,
    deadClicks:  true,
  },

  // Heatmap recording (clicks + scroll on by default; mouse-move opt-in).
  heatmap: {
    enabled: true,
    clicks:  true,
    moves:   false,
    scroll:  true,
  },

});

Nota

Nelle impostazioni Configurazione controllata dal progetto. della Dashboard puoi disattivare i tracker di analytics locali. Replay invece non ha alcun flag locale di attivazione: configuralo in Settings → Session replay e l'SDK applicherà l'ultima policy del progetto al successivo aggiornamento della configurazione.

Eventi tracciati automaticamente

Con la configurazione predefinita, Kixo acquisisce automaticamente questi eventi senza codice aggiuntivo:

page_view — ogni navigazione (caricamento iniziale + cambi di route in una SPA)
session_start / session_end
click — tutti i clic sulle interazioni che corrispondono al selettore dell'elemento
scroll_depth — soglie del 25 / 50 / 75 / 100 %
rage_click — clic ripetuti sullo stesso elemento
dead_click — clic su elementi non interattivi
error — eccezioni JavaScript non intercettate + rifiuti di promise
performance — metriche di caricamento della pagina e Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — tempi delle richieste, se il tracciamento di rete è abilitato
heatmap_click / scroll — dati della heatmap

L’elenco completo è disponibile in Riferimento degli eventi.

Eventi personalizzati

Kixo.track()

Invia un evento personalizzato con proprietà facoltative.

Kixo.track('purchase_completed', {
  product_id: 'SKU-123',
  amount: 49.99,
  currency: 'USD',
});

Helper tipizzati per gli eventi

Scorciatoia su Kixo.track() per gli eventi che Kixo riconosce per nome (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). I wrapper tipizzati offrono la validazione delle proprietà in fase di compilazione e un’unica fonte di verità per i nomi delle chiavi: il rilevatore degli eventi standard nel backend fa corrispondenza letterale.

Kixo.trackPurchase({ amount: 49.99, currency: 'USD', productId: 'pro_yearly' });

Kixo.trackSubscriptionStart({
  plan: 'pro',
  amount: 9.99,
  currency: 'USD',
  interval: 'month',
});

Kixo.trackSignup({ method: 'google' });
Kixo.trackTrialStart({ plan: 'pro', days: 14 });
Kixo.trackCancel({ plan: 'pro', reason: 'too_expensive' });
Kixo.trackUpgrade({ fromPlan: 'free', toPlan: 'pro' });
Kixo.trackActivation({ event: 'first_post_published' });
Kixo.trackShare({ channel: 'twitter', contentId: 'post_123' });
Kixo.trackInvite({ channel: 'email', recipientCount: 5 });

Kixo.identify()

Associa il dispositivo corrente a un utente noto. Le chiavi standard riservate usano il prefisso $ (convenzione Mixpanel), così restano separate dai tuoi attributi personalizzati e vengono promosse nelle colonne del profilo della dashboard. Vedi Catalogo standard delle proprietà qui sotto per l'elenco completo delle 37 chiavi.

Kixo.identify('user_123', {
  $email:  'jane@example.com',     // identity
  $name:   'Jane Doe',              // identity
  $plan:   'pro',                   // subscription pack
  $lifetime_orders: 12,             // e-commerce pack
  signup_source: 'twitter_ad',      // custom trait
});

Kixo.setUserProperty() — assegna un tag a un utente per la segmentazione

Aggiunge all'utente corrente attributi chiave/valore arbitrari. I valori possono essere stringhe, numeri o valori booleani; il formato booleano è il modo più pulito per tag un utente e usarlo poi nel targeting di segmenti, campagne email o query in chat.

// Tag a user as subscribed — instant segment "Subscribed users"
Kixo.setUserProperty('subscribe', true);

// Mark a VIP — used in campaign targeting + chat ("show me VIPs")
Kixo.setUserProperty('vip', true);

// Numeric and string values work too
Kixo.setUserProperty('plan_tier', 'enterprise');
Kixo.setUserProperty('lifetime_orders', 42);

// Bulk-set
Kixo.setUserProperties({ subscribe: true, plan_tier: 'enterprise' });

Le proprietà restano salvate in localStorage tra un reload e l’altro e vengono aggiunte automaticamente agli eventi successivi. Puoi usarle in chat con prompt come "crea una campagna email per gli utenti con subscribe uguale a true": Kixo crea il segmento e prepara automaticamente la bozza del template. Vengono cancellate con Kixo.reset().

Kixo.group()

Associa l'utente a un'azienda o a un'organizzazione.

Kixo.group('company_456', {
  name: 'Acme Inc',
  plan: 'enterprise',
});

Kixo.reset()

Cancella identità, super-property e coda persistita. Chiamalo al logout, così gli eventi successivi non saranno attribuiti all'utente precedente.

Kixo.reset();

Catalogo standard delle proprietà

Le chiavi di proprietà riservate usano il prefisso $, così restano separate dai tuoi trait personalizzati. Il catalogo di Kixo comprende 37 chiavi distribuite in 3 pacchetti universali (identità, geolocalizzazione, ciclo di vita) e 5 pacchetti verticali B2B (abbonamenti, e-commerce, media, marketplace, fedeltà). Imposta solo quelle rilevanti per il tuo prodotto: la dashboard si adatta e mostra soltanto i pacchetti che popolari.

Identità

Sempre rilevante. Imposta le colonne dell'intestazione del profilo.

Chiave	Tipo	Descrizione
`$email`	stringa	Email principale, spesso usata come chiave di unione per la ricomposizione dell’identità.
`$phone`	stringa	Numero di telefono in formato E.164.
`$name`	stringa	Nome visualizzato completo.
`$first_name`	stringa	Nome.
`$last_name`	stringa	Cognome.
`$avatar_url`	stringa	URL completo dell'immagine avatar dell'utente.

Geo

Contesto geografico.

Chiave	Tipo	Descrizione
`$country`	stringa	Codice paese ISO 3166.
`$city`	stringa	Nome della città.
`$region`	stringa	Stato o provincia.
`$timezone`	stringa	Zona IANA come `America/Los_Angeles`.
`$language`	stringa	Tag IETF come `en` o `ru-RU`.
`$locale`	stringa	Identificatore locale completo.

Ciclo di vita

Quando l’abbiamo visto.

Chiave	Tipo	Descrizione
`$created`	ISO8601	Data e ora di registrazione o creazione dell’account.
`$last_seen`	ISO8601	Ora dell’ultima interazione.

Abbonamento

Impostalo se il tuo prodotto prevede piani.

Chiave	Tipo	Descrizione
`$plan`	stringa	Slug del piano — `free`, `pro`, `enterprise`.
`$subscription_status`	stringa	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Data di scadenza del trial attuale.
`$mrr`	numero	Ricavi ricorrenti mensili nella valuta dell’account.
`$subscription_started`	ISO8601	Data di inizio dell’abbonamento attuale.

E-commerce

Impostalo se vendi prodotti.

Chiave	Tipo	Descrizione
`$lifetime_orders`	numero	Numero di ordini completati.
`$lifetime_revenue`	numero	Spesa totale.
`$aov`	numero	Valore medio dell'ordine.
`$last_purchase`	ISO8601	Acquisto più recente concluso con successo.
`$first_purchase`	ISO8601	Primo acquisto completato con successo.
`$cart_abandoned_count`	numero	Numero totale di abbandoni del carrello.

Media

Impostalo se pubblichi contenuti.

Chiave	Tipo	Descrizione
`$content_tier`	stringa	`free` / `premium` / `paid`.
`$subscribed_categories`	Stringa CSV o array	Categorie seguite dall'utente.
`$watch_time_total`	numero	Tempo di visione complessivo in secondi.
`$last_played`	ISO8601	Avvio della riproduzione più recente.

Marketplace

Impostalo se il tuo prodotto è una piattaforma a due versanti.

Chiave	Tipo	Descrizione
`$seller_tier`	stringa	Slug del piano lato venditore.
`$buyer_tier`	stringa	Slug del piano lato acquirente.
`$listings_count`	numero	Annunci attivi dell'utente.
`$reviews_count`	numero	Recensioni ricevute dall’utente.
`$verified`	boolean	Stato KYC.

Fedeltà

Impostalo per programmi di coinvolgimento e ricompense.

Chiave	Tipo	Descrizione
`$loyalty_points`	numero	Saldo attuale dei punti riscattabili.
`$vip_level`	stringa	Slug del piano VIP.
`$referral_count`	numero	Segnalazioni riuscite attribuite a questo utente.

Suggerimento

Non trovi il tuo schema? Usa chiavi semplici per gli attributi personalizzati. Compariranno nel pannello Custom Traits della dashboard senza occupare le colonne del profilo. I 5 pacchetti verticali qui sopra sono ipotesi ragionate sulle strutture B2B più comuni; la terminologia specifica del cliente, ad esempio shipping_plan, resta senza prefisso.

Super-property

Coppie chiave/valore di sessione aggiunte automaticamente a ogni evento in uscita. A differenza dei trait identify(), che descrivono l’identità, le super-property descrivono il contesto della sessione: variante A/B attiva, flavor della build, feature flag attivate, referrer affiliato. Restano salvate in localStorage tra un reload e l’altro e vengono cancellate con reset(). In caso di chiavi duplicate, le properties per evento passate a track() hanno sempre la precedenza.

Kixo.setSuperProperty('build_flavor', 'beta');
Kixo.setSuperProperties({ ab_variant: 'B', referrer_campaign: 'autumn-launch' });

// Sugar for A/B tracking — keys as 'experiment_<id>' so backend
// can run direct WHERE filters on experiment analysis.
Kixo.setExperimentVariant('checkout_v2', 'variant_a');

Kixo.unsetSuperProperty('build_flavor');
Kixo.clearSuperProperties();

Heatmap

La registrazione della heatmap è attiva per default: clic e profondità di scorrimento, entrambi campionati al 100 %. Il movimento del mouse è facoltativo (genera molto volume; attivalo per singola pagina se serve).

Kixo.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey:    'YOUR_API_KEY',
  heatmap:   { moves: true },  // turn on full-resolution mouse-move
});

Replay delle sessioni

Il session replay registra uno snapshot del DOM di rrweb e il flusso delle mutazioni, così la dashboard può ricostruire la pagina come una sessione navigabile affiancata alla traccia degli eventi. È una ricostruzione del DOM, non una registrazione video dello schermo. Replay è disattivato per impostazione predefinita. Puoi abilitarlo per il progetto da Dashboard → Impostazioni → Replay sessione; non serve modificare il codice dell’applicazione. Quando lo abiliti, il recorder viene scaricato da un chunk separato con la stessa versione.

Nota

La dashboard è la fonte di verità. Qui puoi impostare Enable replay, Mask inputs, durata massima e i controlli avanzati di acquisizione. captureOnCellular viene salvato nella stessa policy di progetto per iOS e Android; i browser non espongono in modo affidabile se la connessione è Wi‑Fi o cellulare, quindi il Web SDK segnala e ignora questa restrizione valida solo in ambiente nativo.

Cosa viene mascherato

Replay è progettato per poter essere attivato in sicurezza. I contenuti sensibili sono protetti da tre livelli, tutti abilitati per impostazione predefinita:

Il mascheramento degli input si controlla a livello di progetto — con l'impostazione Maschera gli input della Dashboard attiva per default, i caratteri digitati vengono sostituiti con asterischi prima di lasciare il browser. Disattivala solo per un'esigenza specifica e poco sensibile; i campi di identità, autenticazione e pagamento restano comunque mascherati.
L’attributo data-kixo-mask esclude un elemento e tutto il suo sottoalbero. Applicalo a qualsiasi contenitore che possa includere contenuti personali o riservati: nel replay comparirà un segnaposto, non il testo né il contenuto DOM di quel sottoalbero.
html
```
<div data-kixo-mask>
  
  
</div>
```
I campi sensibili vengono sempre mascherati. — gli input che sembrano contenere password, numeri di carta, CVV, SSN, segreti o token (in base a type, name, id o autocomplete) vengono mascherati anche se l'impostazione Maschera gli input del progetto è disattivata. Anche il testo visibile e gli attributi DOM serializzati passano nel filtro PII di Kixo prima dell'upload.

Raccolta dati

L’SDK acquisisce i tracker abilitati nelle impostazioni dell’integrazione e del progetto, oltre agli eventi e alle proprietà inviati dalla tua applicazione.

Dove finiscono le registrazioni

L’SDK comprime con gzip gli eventi rrweb in segmenti di dimensione limitata, chiede a Kixo un URL di upload firmato con ambito di progetto e carica questi segmenti direttamente nello storage del replay. Puoi aprire la sessione ricostruita in Replay → Sessioni; è collegata alla traccia analitica della stessa sessione.

Nota

Replay è disponibile in base al tuo piano. Il numero di sessioni acquisite e conservate dipende dal piano del progetto; nei piani più bassi Kixo registra comunque metadati di sessione leggeri, così la sessione compare negli elenchi e nelle analisi.

Feature flag

Controlla i valori dei flag a runtime con Kixo.getFeatureFlag().

const variant = Kixo.getFeatureFlag('new_checkout');

if (variant === 'enabled') {
  showNewCheckout();
} else {
  showLegacyCheckout();
}

Invio e comportamento offline

L’SDK accoda gli eventi in locale, li invia in batch e ritenta gli errori temporanei con backoff. Se la raccolta viene sospesa dalle impostazioni del progetto, i nuovi eventi non vengono inviati finché non viene riattivata.

Diagnostica

Stato di salute in sola lettura, utile nei devtools per capire perché gli eventi non stanno arrivando.

const diag = Kixo.diagnostics();
console.log(diag);