SDK web

L’SDK web de Kixo registra automàticament clics, visualitzacions de pàgina, sessions, errors, profunditat de desplaçament, web vitals, rage clicks, dead clicks i dades de mapa de calor amb una sola línia d’inserció. El monitoratge de peticions de xarxa és opcional. Es distribueix com a mòdul ES natiu i funciona en navegadors moderns.

Instal·lació

Etiqueta script (CDN)

Afegeix el fragment abans de l’etiqueta de tancament </head>. Fixa’t en type="module": és obligatori perquè l’SDK és un mòdul ES. La reproducció de sessió es divideix en un fragment del gravador amb la mateixa versió, que només es carrega quan s’ha activat; així el paquet base es manté petit mentre la reproducció està desactivada.

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 llegeix project_id i api_key de la URL del script i s’inicialitza. Si vols configurar opcions des del codi de l’aplicació, elimina els paràmetres de la URL i crida Kixo.init({...}); l’objecte global Kixo estarà disponible quan el mòdul s’hagi carregat.

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

Fes servir aquesta opció si vols configurar opcions des del codi de l’aplicació i no des de la URL del script. Exposa la mateixa API Kixo que la inserció per CDN.

bash

npm install @kixo.io/web

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

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

Plataformes sense codi

Si treballes amb un constructor amb AI com Lovable, Bolt, v0 o Replit, enganxa el fragment amb l’etiqueta script directament al xat del constructor o a la configuració d’injecció de codi. La majoria permeten afegir scripts a <head> del lloc.

Configuració

La inserció de dues línies fa servir els valors locals per defecte d’analítica que tens a continuació. El monitoratge de peticions continua sent opcional. Replay queda expressament fora de Kixo.init(): l’activació, el mostreig, la privacitat, la durada i la configuració de captura només es controlen des del dashboard del projecte.

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

Configuració controlada pel projecte. La configuració del Dashboard pot desactivar els rastrejadors d’analítica locals. La reproducció de sessió no té cap indicador local d’activació forçada: configura-la a Settings → Session replay, i l’SDK aplicarà la política més recent del projecte en la propera actualització de configuració.

Esdeveniments registrats automàticament

Amb la configuració per defecte, Kixo captura automàticament aquests esdeveniments sense codi addicional:

page_view — cada navegació (càrrega inicial + canvis de ruta SPA)
session_start / session_end
click — totes les interaccions de clic amb selector d’element
scroll_depth — llindars del 25 / 50 / 75 / 100 %
rage_click — clics repetits al mateix element
dead_click — clics en elements no interactius
error — excepcions de JavaScript no capturades + rebuigs de promeses
performance — mètriques de càrrega de pàgina i Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — temps de sol·licitud opcionals quan el seguiment de xarxa està activat
heatmap_click / scroll — dades del mapa de calor

Consulta la llista completa a Referència d’esdeveniments.

Esdeveniments personalitzats

Kixo.track()

Envia un esdeveniment personalitzat amb propietats opcionals.

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

Ajudants tipats d’esdeveniments

Sucre sintàctic sobre Kixo.track() per als esdeveniments que Kixo reconeix pel nom (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Aquests wrappers tipats aporten validació de propietats en temps de compilació i una única font de veritat per als noms de clau; el detector d’esdeveniments estàndard del backend hi fa coincidència literal.

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 el dispositiu actual amb un usuari conegut. Les claus de propietat estàndard reservades porten el prefix $ (convenció de Mixpanel), de manera que queden separades dels teus atributs personalitzats i pugen a les columnes de perfil del dashboard; consulta el Catàleg estàndard de propietats de sota per veure la llista completa de 37 claus.

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() — etiqueta un usuari per segmentar-lo

Afegeix atributs clau/valor arbitraris a l’usuari actual. Els valors poden ser cadenes, nombres o booleans; la forma booleana és la manera més neta de etiqueta un usuari per poder-lo segmentar més endavant en segments, campanyes de correu o consultes al xat.

// 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' });

Les propietats es conserven a localStorage entre recàrregues i s’adjunten automàticament als esdeveniments següents. Pots fer-les servir al xat amb instruccions com "crea una campanya de correu electrònic per als usuaris on subscribe sigui true": Kixo genera automàticament el segment i l’esborrany de plantilla. S’esborren amb Kixo.reset().

Kixo.group()

Associa l’usuari amb una empresa o organització.

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

Kixo.reset()

Esborra la identitat, les superpropietats i la cua persistent. Crida-ho en tancar la sessió perquè els esdeveniments posteriors no s’atribueixin a l’usuari anterior.

Kixo.reset();

Catàleg estàndard de propietats

Les claus de propietat reservades porten el prefix $ per no barrejar-se amb els teus trets personalitzats. El catàleg de Kixo inclou 37 claus repartides en 3 paquets universals (identitat, geografia i cicle de vida) i 5 paquets verticals B2B (subscripció, comerç electrònic, mitjans, marketplace i fidelització). Defineix només les que s’apliquin al teu producte: el dashboard s’adapta i només mostra els paquets que tinguis emplenats.

Identitat

Sempre rellevant. Defineix les columnes de capçalera del perfil.

Clau	Tipus	Descripció
`$email`	cadena	Adreça electrònica principal, sovint usada com a clau de fusió per unificar identitats.
`$phone`	cadena	Número de telèfon E.164.
`$name`	cadena	Nom complet visible.
`$first_name`	cadena	Nom.
`$last_name`	cadena	Cognom.
`$avatar_url`	cadena	URL completa de la imatge d’avatar de l’usuari.

Geo

Context geogràfic.

Clau	Tipus	Descripció
`$country`	cadena	Codi de país ISO 3166.
`$city`	cadena	Nom de la ciutat.
`$region`	cadena	Estat o província.
`$timezone`	cadena	Zona IANA com `America/Los_Angeles`.
`$language`	cadena	Etiqueta IETF com `en` o `ru-RU`.
`$locale`	cadena	Identificador de locale complet.

Cicle de vida

Quan l’hem vist.

Clau	Tipus	Descripció
`$created`	ISO8601	Moment del registre o de la creació del compte.
`$last_seen`	ISO8601	Hora de l’última interacció.

Subscripció

Defineix-ho si el teu producte té plans.

Clau	Tipus	Descripció
`$plan`	cadena	Slug del nivell: `free`, `pro`, `enterprise`.
`$subscription_status`	cadena	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Quan caduca el període de prova actual.
`$mrr`	nombre	Ingressos recurrents mensuals en la moneda del compte.
`$subscription_started`	ISO8601	Quan va començar la subscripció actual.

Comerç electrònic

Defineix-ho si vens productes.

Clau	Tipus	Descripció
`$lifetime_orders`	nombre	Nombre de comandes completades.
`$lifetime_revenue`	nombre	Despesa total.
`$aov`	nombre	Valor mitjà de la comanda.
`$last_purchase`	ISO8601	Última compra satisfactòria.
`$first_purchase`	ISO8601	Primera compra completada amb èxit.
`$cart_abandoned_count`	nombre	Nombre total d’abandonaments del carretó.

Mitjans

Defineix-ho si publiques contingut.

Clau	Tipus	Descripció
`$content_tier`	cadena	`free` / `premium` / `paid`.
`$subscribed_categories`	Cadena CSV o matriu	Categories que segueix l’usuari.
`$watch_time_total`	nombre	Temps total de visualització en segons.
`$last_played`	ISO8601	Inici de reproducció més recent.

Marketplace

Defineix-ho si el teu producte és una plataforma de dues bandes.

Clau	Tipus	Descripció
`$seller_tier`	cadena	Slug del nivell del venedor.
`$buyer_tier`	cadena	Slug del nivell del costat comprador.
`$listings_count`	nombre	Anuncis actius que pertanyen a l’usuari.
`$reviews_count`	nombre	Ressenyes rebudes per l’usuari.
`$verified`	booleà	Estat del KYC.

Fidelització

Defineix-ho per a programes d’interacció i de recompenses.

Clau	Tipus	Descripció
`$loyalty_points`	nombre	Saldo actual de punts bescanviables.
`$vip_level`	cadena	Slug del nivell VIP.
`$referral_count`	nombre	Referències satisfactòries atribuïdes a aquest usuari.

Consell

No hi veus el teu patró? Fes servir claus simples per als atributs personalitzats. Apareixeran al panell Custom Traits del dashboard sense embrutar les columnes del perfil. Els 5 paquets verticals de més amunt són propostes orientades a les formes B2B més habituals; la terminologia específica del client (p. ex. shipping_plan) es manté sense prefix.

Superpropietats

Parells clau-valor per sessió que s’adjunten automàticament a tots els esdeveniments sortints. A diferència dels trets identify() (que descriuen la identitat), les superpropietats descriuen el context de la sessió: variant A/B activa, variant de compilació, feature flags activades o referència d’afiliat. Es conserven a localStorage entre recàrregues i s’esborren amb reset(). Si hi ha conflicte de clau, sempre prevalen les properties de l’esdeveniment a track().

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();

Mapes de calor

La gravació de mapes de calor està activada per defecte: clics i profunditat de desplaçament, tots dos amb mostreig del 100 %. El moviment del ratolí és opcional (genera molt volum; activa’l per pàgina si et convé).

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

Reproducció de sessions

Replay registra una instantània del DOM amb rrweb i un flux de mutacions perquè el dashboard pugui reconstruir la pàgina com una sessió navegable al costat del rastre d’esdeveniments. És una reconstrucció del DOM, no una gravació de pantalla en vídeo. Replay està desactivat per defecte. Activa’l per al projecte a Tauler > Configuració > Reproducció de sessions; no cal cap canvi al codi de l’aplicació. Un cop activat, el gravador es descarrega en un fragment independent amb la mateixa versió.

Nota

El dashboard és la font de veritat. Hi pots definir Enable replay, Mask inputs, la durada màxima i els controls avançats de captura. captureOnCellular es desa a la mateixa política de projecte per a iOS i Android; els navegadors no exposen cap senyal fiable per distingir Wi‑Fi de dades mòbils, per això el SDK web informa d’aquesta restricció només nativa i la ignora.

Què s’emmascara

Replay està pensat per poder-se activar amb seguretat. Hi ha tres capes de protecció del contingut sensible, totes activades per defecte:

L’emmascarament dels camps d’entrada es controla des del projecte — mentre l’opció Emmascara els camps d’entrada del Dashboard estigui activada (per defecte), els caràcters escrits se substitueixen per asteriscs abans de sortir del navegador. Desactiva-la només per a una necessitat concreta i poc sensible; els camps d’identitat, autenticació i pagament continuen emmascarats.
L’atribut data-kixo-mask bloqueja un element i tot el seu subarbre. Posa’l a qualsevol contenidor que pugui tenir contingut personal o confidencial; la reproducció mostra un marcador de posició, no pas el text ni el contingut del DOM d’aquell subarbre.
html
```
<div data-kixo-mask>
  
  
</div>
```
Els camps sensibles sempre s’emmascaren — els camps que semblen una contrasenya, un número de targeta, un CVV, un SSN, un secret o un token (pel type, name, id o autocomplete) s’emmascaren encara que l’opció Emmascara els camps d’entrada del projecte estigui desactivada. El text visible i els atributs del DOM serialitzats també passen pel sanejador de PII de Kixo abans de pujar-se.

Recollida de dades

L’SDK captura els trackers activats a la integració i a la configuració del projecte, a més dels esdeveniments i les propietats que envia l’aplicació.

On van a parar les gravacions

L’SDK comprimeix els esdeveniments d’rrweb amb gzip en segments acotats, demana a Kixo una URL de pujada signada per al projecte i puja aquests segments directament a l’emmagatzematge de replay. Obre la sessió reconstruïda a Reproducció > Sessions; enllaça amb el rastre analític de la mateixa sessió.

Nota

Replay depèn del teu pla. Quantes sessions es capturen i es retenen depèn del pla del projecte; als nivells inferiors, Kixo continua registrant metadades de sessió lleugers perquè la sessió aparegui a les llistes i a l’analítica.

Indicadors de funcionalitat

Comprova els valors dels flags en temps d’execució amb Kixo.getFeatureFlag().

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

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

Enviament i comportament fora de línia

L’SDK posa els esdeveniments en cua localment, els envia per lots i reintenta els errors transitoris amb backoff. Si s’atura la recollida des de la configuració del projecte, els esdeveniments nous no s’envien fins que es torna a activar.

Diagnòstics

Instantània d’estat en mode només lectura, útil per depurar a les eines de desenvolupament per què no arriben els esdeveniments.

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