SDK Web

Kixo Web SDK urmărește automat clicuri, afișări de pagină, sesiuni, erori, adâncimea de scroll, Web Vitals, rage click-uri, dead click-uri și date pentru hărți termice, cu o integrare dintr-un singur rând. Monitorizarea cererilor de rețea este disponibilă ca opțiune activată explicit. Este distribuit ca modul nativ ES și funcționează în browsere moderne.

Instalare

Tag script (CDN)

Adaugă fragmentul înainte de tagul de închidere </head>. Observă type="module" — este necesar deoarece SDK-ul este un modul ES. Redarea sesiunilor este separată prin code splitting într-un chunk de recorder cu versiune compatibilă, care se încarcă doar după activarea replay-ului, astfel încât bundle-ul de bază să rămână mic cât timp replay-ul este dezactivat.

html

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

Notă

SDK-ul citește project_id și api_key din URL-ul scriptului și se inițializează singur. Dacă vrei să configurezi opțiunile din codul aplicației, elimină parametrii din URL și apelează Kixo.init({...}) — obiectul global Kixo este disponibil după încărcarea modulului.

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

Folosește această variantă când vrei să configurezi opțiunile din codul aplicației, nu prin URL-ul scriptului. Expune același API Kixo ca integrarea prin CDN.

bash

npm install @kixo.io/web

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

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

Platforme no-code

Dacă lucrezi cu un builder bazat pe AI precum Lovable, Bolt, v0 sau Replit, lipește fragmentul cu tagul script direct în chatul builderului sau în setările lui de injectare a codului. Majoritatea builderelor permit adăugarea scripturilor în <head> site-ului.

Configurare

Integrarea în două rânduri folosește valorile locale implicite de analytics de mai jos. Monitorizarea cererilor rămâne opțională. Session replay lipsește intenționat din Kixo.init(): activarea, eșantionarea, confidențialitatea, durata și setările de captură se controlează exclusiv din dashboardul proiectului.

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,
  },

});

Notă

Setările Configurație controlată la nivel de proiect. din Dashboard pot dezactiva trackerele locale de analytics. Replay nu are deloc un indicator local de activare: îl configurezi din Settings → Session replay, iar SDK aplică cea mai recentă politică a proiectului la următoarea reîmprospătare a configurației.

Evenimente urmărite automat

Cu configurația implicită, Kixo captează automat aceste evenimente, fără cod suplimentar:

page_view — fiecare navigare (încărcarea inițială + schimbările de rută din SPA)
session_start / session_end
click — toate interacțiunile de clic, împreună cu selectorul elementului
scroll_depth — praguri de 25 / 50 / 75 / 100 %
rage_click — clicuri repetate pe același element
dead_click — clicuri pe elemente neinteractive
error — excepții JavaScript neinterceptate + respingeri de promise
performance — metrici de încărcare a paginii și Web Vitals (LCP, FCP, FID, CLS, INP, TTFB)
network_request — timpi opționali ai cererilor, când monitorizarea rețelei este activată
heatmap_click / scroll — date pentru harta termică

Vezi lista completă în Referință pentru evenimente.

Evenimente personalizate

Kixo.track()

Trimite un eveniment personalizat, cu proprietăți opționale.

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

Helpere de evenimente tipate

Un strat de conveniență peste Kixo.track() pentru evenimentele pe care Kixo le recunoaște după nume (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Aceste helpere tipate oferă validarea proprietăților la compilare și o singură sursă de adevăr pentru numele cheilor — detectorul de evenimente standard din backend potrivește numele exact, 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()

Asociază dispozitivul curent cu un utilizator cunoscut. Cheile standard rezervate pentru proprietăți au prefixul $ (convenția Mixpanel), ca să fie separate de atributele tale personalizate și să fie promovate în coloanele de profil din dashboard — vezi Catalogul standard de proprietăți de mai jos pentru lista completă cu 37 de chei.

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() — etichetează un utilizator pentru segmentare

Atașează utilizatorului curent atribute arbitrare cheie/valoare. Valorile pot fi șiruri de caractere, numere sau valori booleene — forma booleană este cea mai curată metodă de a etichetă un utilizator pentru targetare ulterioară în segmente, campanii de email sau interogări în 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' });

Proprietățile se păstrează în localStorage între reîncărcări și se atașează automat evenimentelor următoare. Le poți folosi în chat cu prompturi precum „creează o campanie de email pentru utilizatorii la care subscribe este true” — Kixo construiește automat segmentul și pregătește șablonul. Se șterg la Kixo.reset().

Kixo.group()

Asociază utilizatorul cu o companie sau o organizație.

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

Kixo.reset()

Șterge identitatea, super-proprietățile și coada persistentă. Apelează această funcție la logout, ca evenimentele ulterioare să nu mai fie atribuite utilizatorului anterior.

Kixo.reset();

Catalogul standard de proprietăți

Cheile de proprietăți rezervate folosesc prefixul $, ca să nu intre în conflict cu trăsăturile tale personalizate. Catalogul Kixo acoperă 37 de chei în 3 pachete universale (identitate, geo, ciclu de viață) și 5 pachete verticale B2B (abonamente, e-commerce, media, marketplace, loialitate). Setează doar ce se aplică produsului tău — dashboardul se adaptează și afișează doar pachetele pe care le populezi.

Identitate

Întotdeauna relevant. Definește coloanele din antetul profilului.

Cheie	Tip	Descriere
`$email`	șir de caractere	Adresa principală de e-mail, folosită adesea ca cheie de unificare a identității.
`$phone`	șir de caractere	Număr de telefon în format E.164.
`$name`	șir de caractere	Numele complet afișat.
`$first_name`	șir de caractere	Prenume.
`$last_name`	șir de caractere	Nume de familie.
`$avatar_url`	șir de caractere	URL-ul complet al imaginii de avatar a utilizatorului.

Geo

Context geografic.

Cheie	Tip	Descriere
`$country`	șir de caractere	Cod de țară ISO 3166.
`$city`	șir de caractere	Numele orașului.
`$region`	șir de caractere	Stat sau provincie.
`$timezone`	șir de caractere	Zonă IANA precum `America/Los_Angeles`.
`$language`	șir de caractere	Etichetă IETF precum `en` sau `ru-RU`.
`$locale`	șir de caractere	Identificator complet de localizare.

Ciclu de viață

Când l-am văzut.

Cheie	Tip	Descriere
`$created`	ISO8601	Momentul înregistrării sau al creării contului.
`$last_seen`	ISO8601	Ora ultimei interacțiuni.

Abonament

Folosește-l dacă produsul tău are planuri.

Cheie	Tip	Descriere
`$plan`	șir de caractere	Slug-ul nivelului — `free`, `pro`, `enterprise`.
`$subscription_status`	șir de caractere	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Când expiră perioada de probă curentă.
`$mrr`	număr	Venitul recurent lunar, în moneda contului.
`$subscription_started`	ISO8601	Când a început abonamentul curent.

Comerț electronic

Folosește-l dacă vinzi produse.

Cheie	Tip	Descriere
`$lifetime_orders`	număr	Numărul de comenzi finalizate.
`$lifetime_revenue`	număr	Cheltuieli totale.
`$aov`	număr	Valoarea medie a comenzii.
`$last_purchase`	ISO8601	Cea mai recentă achiziție finalizată cu succes.
`$first_purchase`	ISO8601	Prima achiziție reușită.
`$cart_abandoned_count`	număr	Numărul total de abandonuri de coș.

Media

Folosește-l dacă publici conținut.

Cheie	Tip	Descriere
`$content_tier`	șir de caractere	`free` / `premium` / `paid`.
`$subscribed_categories`	șir CSV sau tablou	Categoriile urmărite de utilizator.
`$watch_time_total`	număr	Timpul total de vizionare, în secunde.
`$last_played`	ISO8601	Cea mai recentă pornire a redării.

Marketplace

Folosește-l dacă produsul tău este o platformă cu două laturi.

Cheie	Tip	Descriere
`$seller_tier`	șir de caractere	Slug-ul nivelului pe partea vânzătorului.
`$buyer_tier`	șir de caractere	Slug-ul nivelului de pe partea cumpărătorului.
`$listings_count`	număr	Listări active deținute de utilizator.
`$reviews_count`	număr	Recenziile primite de utilizator.
`$verified`	boolean	Stare KYC.

Loialitate

Folosește-l pentru programe de engagement și recompense.

Cheie	Tip	Descriere
`$loyalty_points`	număr	Soldul curent de puncte care pot fi folosite.
`$vip_level`	șir de caractere	Slug-ul nivelului VIP.
`$referral_count`	număr	Recomandări reușite atribuite acestui utilizator.

Sfat

Nu-ți regăsești modelul? Folosește chei simple pentru atribute personalizate. Ele apar în panoul Custom Traits din dashboard fără să încarce coloanele de profil. Cele 5 pachete verticale de mai sus sunt presupuneri informate despre cele mai comune structuri B2B — terminologia specifică fiecărui client (de exemplu shipping_plan) rămâne fără prefix.

Super-proprietăți

Perechi cheie-valoare la nivel de sesiune, atașate automat fiecărui eveniment trimis. Spre deosebire de trăsăturile identify(), care descriu identitatea, super-proprietățile descriu contextul sesiunii — varianta A/B activă, tipul de build, feature flag-urile activate sau sursa afiliată. Se păstrează în localStorage între reîncărcări și se șterg la reset(). Dacă există chei identice, proprietățile properties setate pe track() la nivel de eveniment au întotdeauna prioritate.

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

Hărți termice

Înregistrarea pentru harta termică este activă implicit — clicurile și adâncimea de derulare, ambele eșantionate la 100 %. Mișcarea mouse-ului este opțională (volum mare; activeaz-o per pagină doar dacă este utilă).

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

Reluarea sesiunii

Session replay înregistrează un instantaneu rrweb al DOM și fluxul de mutații, astfel încât dashboardul să poată reconstrui pagina ca o sesiune derulabilă, alături de traseul evenimentelor. Este o reconstrucție de DOM, nu o înregistrare video a ecranului. Replay este dezactivat implicit. Activează-l pentru proiect din Panou de control → Setări → Redare sesiune; nu e nevoie de modificări în codul aplicației. După activare, recorderul este încărcat dintr-un chunk separat, cu versiune compatibilă.

Notă

Dashboardul este sursa de adevăr. Acolo configurezi Enable replay, Mask inputs, durata maximă și controalele avansate de captură. captureOnCellular este stocat în aceeași politică de proiect pentru iOS și Android; browserele nu oferă un semnal fiabil pentru diferențierea dintre Wi‑Fi și rețeaua celulară, așa că SDK-ul Web raportează și ignoră această restricție disponibilă doar pe nativ.

Ce se maschează

Replay este conceput să poată fi activat în siguranță. Conținutul sensibil este protejat prin trei straturi, toate active implicit:

Mascarea câmpurilor este controlată la nivel de proiect — cât timp setarea Maschează câmpurile din Dashboard este activă (implicit), caracterele tastate sunt înlocuite cu asteriscuri înainte să părăsească browserul. Dezactiveaz-o doar pentru un caz punctual, cu sensibilitate redusă; câmpurile de identitate, autentificare și plată rămân mascate.
Atributul data-kixo-mask blochează un element și întregul lui subarbore. Pune-l pe orice container care poate conține date personale sau confidențiale; redarea va include un substituent, nu textul sau conținutul DOM din acel subarbore.
html
```
<div data-kixo-mask>
  
  
</div>
```
Câmpurile sensibile sunt întotdeauna mascate — câmpurile de introducere care par a fi pentru parolă, număr de card, CVV, SSN, secret sau token (după type, name, id ori autocomplete) sunt mascate chiar și când setarea Maschează câmpurile a proiectului este dezactivată. Textul vizibil și atributele DOM serializate trec și prin filtrul PII din Kixo înainte de încărcare.

Colectarea datelor

SDK-ul captează trackerele activate în integrare și în setările proiectului, plus evenimentele și proprietățile trimise de aplicație.

Unde ajung înregistrările

SDK-ul comprimă cu gzip evenimentele rrweb în segmente cu dimensiune limitată, cere de la Kixo un URL semnat, limitat la proiect, pentru încărcare și trimite acele segmente direct în stocarea de replay. Deschide sesiunea reconstruită în Replay → Sesiuni; de acolo poți ajunge și la traseul analitic al aceleiași sesiuni.

Notă

Replay este disponibil în funcție de planul tău. Câte sesiuni sunt capturate și păstrate depinde de planul proiectului; pe nivelurile inferioare, Kixo înregistrează totuși metadate ușoare de sesiune, astfel încât sesiunea să apară în liste și în analytics.

Flaguri de funcționalitate

Verifică valorile flagurilor la rulare cu Kixo.getFeatureFlag().

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

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

Livrare și comportament offline

SDK-ul pune evenimentele în coadă local, le trimite în loturi și reîncearcă erorile tranzitorii cu backoff. Dacă colectarea este pusă pe pauză din setările proiectului, evenimentele noi nu mai sunt trimise până când colectarea este reactivată.

Diagnosticare

Instantaneu read-only al stării, util în dev tools când depanezi întrebări de tipul „de ce nu ajung evenimentele?”.

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