Web SDK

Kixo Web SDK seuraa yhden rivin upotuksella automaattisesti klikkauksia, sivunäkymiä, istuntoja, virheitä, vierityssyvyyttä, web vitals -mittareita, rage click- ja dead click -tilanteita sekä lämpökarttadataa. Verkkopyyntöjen seuranta on saatavilla erikseen käyttöön otettavana asetuksena. Jaellaan natiivina ES-moduulina, ja se toimii moderneissa selaimissa.

Asennus

Script-tagi (CDN)

Lisää koodikatkelma ennen sulkevaa </head>-tagia. Huomaa type="module" — se on pakollinen, koska SDK on ES-moduuli. Session replay on pilkottu erilliseen, versiota vastaavaan recorder-osaan, joka latautuu vasta, kun replay on otettu käyttöön. Näin peruspaketti pysyy pienenä, kun replay ei ole käytössä.

html

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

Huomautus

SDK lukee project_id:n ja api_key:n skriptin URL:stä ja alustaa itsensä. Jos haluat määrittää asetukset sovelluskoodissa, jätä URL-parametrit pois ja kutsu sen sijaan Kixo.init({...}) — globaali objekti Kixo on käytettävissä, kun moduuli on latautunut.

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

Käytä tätä, kun haluat määrittää asetukset sovelluskoodissa etkä skriptin URL:n kautta. Se tarjoaa saman Kixo API:n kuin CDN-upotus.

bash

npm install @kixo.io/web

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

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

No-code-alustat

Jos rakennat AI-pohjaisella työkalulla kuten Lovable, Bolt, v0 tai Replit, liitä script-tag-katkelma suoraan työkalun chattiin tai koodinlisäysasetuksiin. Useimmat työkalut tukevat skriptien lisäämistä sivuston <head>-osaan.

Asetukset

Kahden rivin upotus käyttää alla olevia paikallisia analytiikan oletuksia. Pyyntöjen seuranta on edelleen erikseen käyttöön otettava asetus. Session replay puuttuu tarkoituksella kohdasta Kixo.init(): käyttöönotto, otanta, tietosuoja, kesto ja tallennusasetukset määritetään vain projektin dashboardissa.

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

});

Huomautus

Projektin ohjaama määritys. Dashboardin asetuksista voi poistaa paikalliset analytiikkaseurannat käytöstä. Replaylla ei ole lainkaan paikallista käyttöönottolippua: määritä se kohdassaSettings → Session replay, niin SDK noudattaa uusinta projektikäytäntöä seuraavan asetuspäivityksen yhteydessä.

Automaattisesti seuratut tapahtumat

Oletusasetuksilla Kixo kerää nämä tapahtumat automaattisesti ilman lisäkoodia:

page_view — kaikki siirtymät (alkulataus + SPA-reittimuutokset)
session_start / session_end
click — kaikki klikkausvuorovaikutukset elementtivalitsimen perusteella
scroll_depth — 25 / 50 / 75 / 100 %:n rajat
rage_click — toistuvat klikkaukset samaan elementtiin
dead_click — klikkaukset ei-interaktiivisiin elementteihin
error — käsittelemättömät JavaScript-poikkeukset ja promise-hylkäykset
performance — sivulatauksen ja Web Vitalsin mittarit (LCP, FCP, FID, CLS, INP, TTFB)
network_request — valinnainen pyyntöjen ajoitustieto, kun verkkoseuranta on käytössä
heatmap_click / scroll — lämpökarttadata

Täysi luettelo on kohdassa Tapahtumaviite.

Mukautetut tapahtumat

Kixo.track()

Lähetä mukautettu tapahtuma halutessasi ominaisuuksien kanssa.

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

Tyypitetyt tapahtuma-apurit

Kevyt kerros Kixo.track():n päälle tapahtumille, jotka Kixo tunnistaa nimeltä (purchase, signup, subscribe_start, trial_start, cancel, upgrade, activation, share, invite). Tyypitetyt wrapperit tuovat ominaisuuksille käännösaikaisen validoinnin ja pitävät avainnimet yhdessä paikassa — backendin vakiotapahtumien tunnistin vertaa niitä sanatarkasti.

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

Yhdistä nykyinen laite tunnettuun käyttäjään. Varatut vakio-ominaisuusavaimet käyttävät $-etuliitettä (Mixpanel-käytännön mukaisesti), jotta ne erottuvat omista mukautetuista ominaisuuksistasi ja nousevat dashboardin profiilisarakkeisiin — koko 37 avaimen lista on alla kohdassa Vakio-ominaisuuksien luettelo.

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() — merkitse käyttäjä segmentointia varten

Liitä nykyiseen käyttäjään vapaavalintaisia avain–arvo-ominaisuuksia. Arvot voivat olla merkkijonoja, numeroita tai totuusarvot — boolean-arvo on selkein tapa tagi käyttäjä myöhempää kohdistusta varten segmenteissä, sähköpostikampanjoissa tai chat-kyselyissä.

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

Ominaisuudet säilyvät localStorage:ssä sivunlatausten yli ja liitetään automaattisesti seuraaviin tapahtumiin. Käytä niitä chatissa kehotteilla kuten "rakenna sähköpostikampanja käyttäjille, joilla subscribe on true" — Kixo muodostaa segmentin ja laatii viestipohjan automaattisesti. Ne tyhjennetään komennolla Kixo.reset().

Kixo.group()

Yhdistä käyttäjä yritykseen tai organisaatioon.

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

Kixo.reset()

Tyhjentää identiteetin, super properties -arvot ja pysyvän jonon. Kutsu tätä uloskirjautumisen yhteydessä, jotta seuraavia tapahtumia ei kohdisteta edelliseen käyttäjään.

Kixo.reset();

Vakio-ominaisuuksien luettelo

Varatut ominaisuusavaimet saavat etuliitteen $, jotta ne pysyvät erillään omista mukautetuista ominaisuuksistasi. Kixon luettelossa on 37 avainta 3 yleisessä paketissa (identiteetti, sijainti, elinkaari) ja 5 B2B-vertikaalipaketissa (tilaus, verkkokauppa, media, markkinapaikka, kanta-asiakkuus). Ota käyttöön tuotteellesi olennaiset paketit — dashboard mukautuu ja näyttää vain ne, joihin tuot dataa.

Identiteetti

Aina relevantti. Määrittää profiiliotsikon sarakkeet.

Avain	Tyyppi	Kuvaus
`$email`	merkkijono	Ensisijainen sähköpostiosoite, usein yhdistämisavaimena identiteettien yhdistelyssä.
`$phone`	merkkijono	E.164-muotoinen puhelinnumero.
`$name`	merkkijono	Koko näytettävä nimi.
`$first_name`	merkkijono	Etunimi.
`$last_name`	merkkijono	Sukunimi.
`$avatar_url`	merkkijono	Käyttäjän avatar-kuvan täydellinen URL.

Sijainti

Maantieteellinen konteksti.

Avain	Tyyppi	Kuvaus
`$country`	merkkijono	ISO 3166 -maakoodi.
`$city`	merkkijono	Kaupungin nimi.
`$region`	merkkijono	Osavaltio tai provinssi.
`$timezone`	merkkijono	IANA-aikavyöhyke, kuten `America/Los_Angeles`.
`$language`	merkkijono	IETF-tunniste, kuten `en` tai `ru-RU`.
`$locale`	merkkijono	Täydellinen kielialuetunniste.

Elinkaari

Milloin näimme hänet.

Avain	Tyyppi	Kuvaus
`$created`	ISO8601	Rekisteröitymisen tai tilin luonnin ajankohta.
`$last_seen`	ISO8601	Viimeisin vuorovaikutusaika.

Tilaus

Aseta tämä, jos tuotteessasi on palvelupaketteja.

Avain	Tyyppi	Kuvaus
`$plan`	merkkijono	Tason tunniste — `free`, `pro`, `enterprise`.
`$subscription_status`	merkkijono	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Milloin nykyinen kokeilujakso päättyy.
`$mrr`	numero	Kuukausittainen toistuva liikevaihto tilin valuutassa.
`$subscription_started`	ISO8601	Milloin nykyinen tilaus alkoi.

Verkkokauppa

Aseta tämä, jos myyt tuotteita.

Avain	Tyyppi	Kuvaus
`$lifetime_orders`	numero	Valmiiden tilausten määrä.
`$lifetime_revenue`	numero	Kokonaiskulutus.
`$aov`	numero	Keskimääräinen tilausarvo.
`$last_purchase`	ISO8601	Viimeisin onnistunut osto.
`$first_purchase`	ISO8601	Ensimmäinen onnistunut osto.
`$cart_abandoned_count`	numero	Ostoskorin hylkäysten kokonaismäärä.

Media

Aseta tämä, jos julkaiset sisältöä.

Avain	Tyyppi	Kuvaus
`$content_tier`	merkkijono	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV-merkkijono tai taulukko	Kategoriat, joita käyttäjä seuraa.
`$watch_time_total`	numero	Katseluaika yhteensä sekunteina.
`$last_played`	ISO8601	Viimeisin toiston aloitus.

Markkinapaikka

Aseta tämä, jos tuotteesi on kaksipuolinen alusta.

Avain	Tyyppi	Kuvaus
`$seller_tier`	merkkijono	Myyjäpuolen tason tunniste.
`$buyer_tier`	merkkijono	Ostajapuolen tasotunnus.
`$listings_count`	numero	Käyttäjän omistamat aktiiviset ilmoitukset.
`$reviews_count`	numero	Käyttäjän saamat arvostelut.
`$verified`	totuusarvo	KYC-tila.

Kanta-asiakkuus

Aseta tämä, jos käytössäsi on sitouttamis- tai palkitsemisohjelmia.

Avain	Tyyppi	Kuvaus
`$loyalty_points`	numero	Lunastettavissa olevien pisteiden nykyinen saldo.
`$vip_level`	merkkijono	VIP-tason tunniste.
`$referral_count`	numero	Tälle käyttäjälle kohdistetut onnistuneet suosittelut.

Vinkki

Etkö löydä omaan malliin sopivaa vaihtoehtoa? Käytä mukautetuille ominaisuuksille pelkkiä avaimia. Ne näkyvät dashboardin Custom Traits -paneelissa sotkematta profiilisarakkeita. Yllä olevat viisi toimialapakettia ovat tarkoituksella valittuja oletuksia yleisimpiin B2B-malleihin — asiakaskohtainen terminologia (esim. shipping_plan) jätetään ilman etuliitettä.

Super-properties

Istuntokohtaiset avain–arvo-parit, jotka liitetään automaattisesti jokaiseen lähtevään tapahtumaan. Ne eroavat identify()-ominaisuuksista, jotka kuvaavat identiteettiä; super-properties kuvaavat istunnon kontekstia, kuten aktiivista A/B-varianttia, build-versiota, käyttöön otettuja feature flageja tai affiliate-viitettä. Ne säilyvät localStorage:ssä sivunlatausten yli ja tyhjennetään komennolla reset(). Tapahtumakohtaiset properties-arvot kutsussa track() voittavat aina avainristiriidassa.

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

Lämpökartat

Lämpökarttatallennus on oletuksena käytössä: klikkaukset ja vierityssyvyys, molemmat 100 %:n otannalla. Hiiren liikkeen tallennus on valinnainen ja volyymiltaan suuri, joten ota se käyttöön sivukohtaisesti vain tarvittaessa.

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

Istunnon toisto

Session replay tallentaa rrwebin DOM-tilannekuvan ja muutosvirran, jotta dashboard voi rakentaa sivun uudelleen kelattavana istuntona tapahtumapolun rinnalle. Kyse on DOM-rakenteen rekonstruoinnista, ei ruuduntallennusvideosta. Replay on pois käytöstä oletuksena. Ota se käyttöön projektille kohdassa Hallintapaneeli → Asetukset → Istunnon tallenne; sovelluskoodia ei tarvitse muuttaa. Kun replay on käytössä, tallennin ladataan erillisestä, versiota vastaavasta chunkista.

Huomautus

Dashboard on ensisijainen totuuden lähde. Määritä siellä Enable replay, Mask inputs, enimmäiskesto ja edistyneet tallennusasetukset. captureOnCellular tallennetaan samaan projektikäytäntöön iOS:lle ja Androidille; selaimet eivät tarjoa luotettavaa tietoa Wi-Fin ja mobiilidatan välillä, joten Web SDK raportoi tämän mutta ohittaa rajoituksen, joka koskee vain natiivisovelluksia.

Mitä peitetään

Replay on suunniteltu turvalliseksi ottaa käyttöön. Arkaluonteista sisältöä suojaa kolme kerrosta, jotka ovat kaikki oletuksena käytössä:

Syötekenttien peittäminen määräytyy projektiasetuksista. — kun Dashboardin Peitä syötteet on käytössä (oletus), kirjoitetut merkit korvataan tähdillä jo ennen kuin ne poistuvat selaimesta. Poista asetus käytöstä vain rajattuun ja vähän arkaluonteiseen tarpeeseen; henkilöllisyys-, tunnistautumis- ja maksukentät pysyvät silti peitettyinä.
Attribuutti data-kixo-mask peittää elementin ja koko sen alipuun. Lisää se mihin tahansa säilöön, jossa voi olla henkilötietoja tai muuta luottamuksellista sisältöä; tallenteeseen tulee paikkamerkki, ei kyseisen alipuun tekstiä tai DOM-sisältöä.
html
```
<div data-kixo-mask>
  
  
</div>
```
Arkaluonteiset kentät peitetään aina. — syötteet, jotka näyttävät salasanalta, korttinumerolta, CVV:ltä, SSN:ltä, salaisuudelta tai tokenilta (tyypin, nimen, id:n tai autocomplete-arvon perusteella), peitetään, vaikka projektin Peitä syötteet olisi pois käytöstä. Myös näkyvä teksti ja sarjoitetut DOM-attribuutit kulkevat ennen lähetystä Kixo:n PII-suodatuksen läpi.

Tiedonkeruu

The SDK kerää integraatiossa ja projektiasetuksissa käyttöön otetut seurannat sekä sovelluksesi lähettämät tapahtumat ja ominaisuudet.

Minne tallenteet päätyvät

SDK pakkaa rrweb-tapahtumat gzipillä rajattuihin segmentteihin, pyytää Kixo:lta projektikohtaisen allekirjoitetun upload-URL:n ja lataa segmentit suoraan replay-tallennukseen. Avaa rekonstruoitu istunto kohdasta Tallenteet → Istunnot; se linkittyy saman istunnon analytiikkapolkuun.

Huomautus

Replayn saatavuus riippuu tilauspaketistasi. Tallennettavien ja säilytettävien istuntojen määrä riippuu projektin paketista. Alemmilla tasoilla Kixo tallentaa silti kevyet istunnon metatiedot-tiedot, jotta istunto näkyy listoissa ja analytiikassa.

Feature flagit

Tarkista flagien arvot ajon aikana kutsulla Kixo.getFeatureFlag().

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

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

Lähetys ja toiminta offline-tilassa

SDK jonottaa tapahtumat paikallisesti, lähettää ne erissä ja yrittää tilapäiset virheet uudelleen kasvavalla viiveellä. Jos keruu keskeytetään projektiasetuksista, uusia tapahtumia ei lähetetä ennen kuin keruu otetaan taas käyttöön.

Diagnostiikka

Vain luku -tilannekuva järjestelmän tilasta — hyödyllinen dev tools -vianmäärityksessä, kun mietit, miksi tapahtumat eivät kulje.

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