Web SDK

Kixo Web SDK, tek satırlık bir eklemeyle tıklamaları, sayfa görüntülemelerini, oturumları, hataları, kaydırma derinliğini, web yaşam göstergelerini, öfke tıklamalarını, boşa tıklamaları ve ısı haritası verilerini otomatik izler. Ağ isteği izleme isteğe bağlı bir ayardır. Yerel bir ES modülü olarak dağıtılır ve modern tarayıcılarda çalışır.

Kurulum

Script etiketi (CDN)

Snippet’i kapanış </head> etiketinden hemen önce ekleyin. type="module" özniteliğine dikkat edin; SDK bir ES modülü olduğu için zorunludur. Session replay, sürümle eşleşen ayrı bir recorder parçasına bölünmüştür ve yalnızca replay etkinleştirildikten sonra yüklenir. Böylece replay kapalıyken temel paket küçük kalır.

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, script URL'sindeki project_id ve api_key değerlerini okuyup kendini başlatır. Seçenekleri uygulama kodunda yapılandırmak istiyorsanız URL parametrelerini kaldırın ve onun yerine Kixo.init({...}) çağrısını kullanın — modül yüklendikten sonra genel Kixo nesnesi kullanılabilir olur.

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

Seçenekleri script URL'si yerine uygulama kodunda yapılandırmak istediğinizde bunu kullanın. CDN eklemesiyle aynı Kixo API'sini sunar.

bash

npm install @kixo.io/web

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

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

Kodsuz Platformlar

Lovable, Bolt, v0 veya Replit gibi AI destekli bir site oluşturucu kullanıyorsanız script etiketi snippet’ini doğrudan oluşturucunuzun sohbetine ya da kod ekleme ayarlarına yapıştırın. Çoğu oluşturucu, sitenizin <head> bölümüne script eklemeyi destekler.

Yapılandırma

İki satırlık ekleme, aşağıdaki yerel analiz varsayılanlarını kullanır. İstek izleme isteğe bağlı olmaya devam eder. Oturum yeniden oynatma bilerek Kixo.init() içinde yer almaz; etkinleştirme, örnekleme, gizlilik, süre ve kayıt ayarları yalnızca proje panosundan gelir.

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

Proje tarafından yönetilen yapılandırma. Dashboard ayarları, yerel analitik izleyicilerini devre dışı bırakabilir. Replay için yerelde ayrı bir açık bayrağı yoktur: bunu Settings → Session replay altında yapılandırın; SDK, bir sonraki yapılandırma yenilemesinde en güncel proje politikasını uygular.

Otomatik izlenen etkinlikler

Varsayılan yapılandırmada Kixo, ek koda gerek duymadan şu olayları otomatik toplar:

page_view — tüm gezinmeler (ilk yükleme + SPA rota değişiklikleri)
session_start / session_end
click — öğe seçicisiyle eşleşen tüm tıklama etkileşimleri
scroll_depth — %25 / %50 / %75 / %100 eşikleri
rage_click — aynı öğe üzerindeki tekrarlı tıklamalar
dead_click — etkileşimli olmayan öğelere yapılan tıklamalar
error — yakalanmamış JavaScript istisnaları + promise redleri
performance — sayfa yükleme ve Web Vitals metrikleri (LCP, FCP, FID, CLS, INP, TTFB)
network_request — ağ izleme açıkken isteğe bağlı istek zamanlaması
heatmap_click / scroll — ısı haritası verileri

Tam liste için Etkinlik referansı bölümüne bakın.

Özel etkinlikler

Kixo.track()

İsteğe bağlı özelliklerle özel bir olay gönderin.

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

Tür denetimli olay yardımcıları

Kixo'nun adıyla tanıdığı olaylar (purchase, signup, subscribe_start,trial_start, cancel, upgrade,activation, share, invite) için Kixo.track() üzerine eklenmiş bir kolaylık katmanı. Tür denetimli sarmalayıcılar, özellikleri derleme anında doğrular ve anahtar adları için tek bir doğruluk kaynağı sağlar; arka uçtaki standart olay algılayıcısı adları birebir eşleştirir.

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

Geçerli cihazı bilinen bir kullanıcıyla ilişkilendirin. Ayrılmış standart özellik anahtarları $ öneki taşır (Mixpanel geleneği); böylece kendi özel trait’lerinizden ayrılır ve dashboard’daki profil sütunlarına yükselir. Tüm 37 anahtarın listesi için aşağıdaki Standart özellik kataloğu bölümüne bakın.

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() — segmentasyon için kullanıcı etiketleme

Geçerli kullanıcıya istediğiniz anahtar/değer özelliklerini ekleyin. Değerler metin, sayı veya boolean değerler olabilir; boolean biçimi, kullanıcıyı daha sonra segmentlerde, e-posta kampanyalarında veya chat sorgularında etiket için en temiz yoldur.

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

Özellikler, yenilemeler arasında localStorage içinde saklanır ve sonraki olaylara otomatik eklenir. Bunları sohbette "subscribe değeri true olan kullanıcılar için bir e-posta kampanyası oluştur" gibi istemlerle kullanın; Kixo segmenti oluşturur ve şablon taslağını otomatik hazırlar. Kixo.reset() ile temizlenir.

Kixo.group()

Kullanıcıyı bir şirket veya kuruluşla ilişkilendirin.

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

Kixo.reset()

Kimliği, super-properties’i ve kalıcı kuyruğu temizleyin. Sonraki etkinliklerin önceki kullanıcıya yazılmaması için çıkışta bunu çağırın.

Kixo.reset();

Standart özellik kataloğu

Ayrılmış özellik anahtarları, özel trait'lerinizle çakışmaması için $ öneki taşır. Kixo kataloğunda 3 evrensel paket (kimlik, coğrafya, yaşam döngüsü) ve 5 B2B dikey paketinde (abonelik, e-ticaret, medya, pazaryeri, sadakat) toplam 37 anahtar bulunur. Ürününüz için geçerli olanları ayarlayın; pano buna uyum sağlar ve yalnızca doldurduğunuz paketleri gösterir.

Kimlik

Her zaman anlamlıdır. Profil başlığındaki sütunları belirler.

Anahtar	Tür	Açıklama
`$email`	dize	Birincil e-posta; kimlik birleştirmede çoğu zaman eşleştirme anahtarı olarak kullanılır.
`$phone`	dize	E.164 telefon numarası.
`$name`	dize	Tam görünen ad.
`$first_name`	dize	Ad.
`$last_name`	dize	Soyadı.
`$avatar_url`	dize	Kullanıcının avatar görselinin tam URL’si.

Coğrafi

Coğrafi bağlam.

Anahtar	Tür	Açıklama
`$country`	dize	ISO 3166 ülke kodu.
`$city`	dize	Şehir adı.
`$region`	dize	Eyalet veya il.
`$timezone`	dize	`America/Los_Angeles` gibi bir IANA zaman dilimi.
`$language`	dize	`en` veya `ru-RU` gibi bir IETF etiketi.
`$locale`	dize	Tam yerel ayar tanımlayıcısı.

Yaşam döngüsü

Onu ne zaman gördük?

Anahtar	Tür	Açıklama
`$created`	ISO8601	Kayıt veya hesap oluşturma zamanı.
`$last_seen`	ISO8601	Son etkileşim zamanı.

Abonelik

Ürününüzde planlar varsa ayarlayın.

Anahtar	Tür	Açıklama
`$plan`	dize	Kademe slug'ı — `free`, `pro`, `enterprise`.
`$subscription_status`	dize	`active` / `trial` / `cancelled` / `past_due`.
`$trial_ends`	ISO8601	Geçerli denemenin biteceği zaman.
`$mrr`	sayı	Hesap para birimindeki aylık yinelenen gelir.
`$subscription_started`	ISO8601	Geçerli aboneliğin başladığı zaman.

E-ticaret

Ürün satıyorsanız ayarlayın.

Anahtar	Tür	Açıklama
`$lifetime_orders`	sayı	Tamamlanan sipariş sayısı.
`$lifetime_revenue`	sayı	Toplam harcama.
`$aov`	sayı	Ortalama sipariş değeri.
`$last_purchase`	ISO8601	En son başarılı satın alma.
`$first_purchase`	ISO8601	İlk başarılı satın alma.
`$cart_abandoned_count`	sayı	Toplam sepet terk etme sayısı.

Medya

İçerik yayımlıyorsanız ayarlayın.

Anahtar	Tür	Açıklama
`$content_tier`	dize	`free` / `premium` / `paid`.
`$subscribed_categories`	CSV metni veya dizi	Kullanıcının takip ettiği kategoriler.
`$watch_time_total`	sayı	Toplam izleme süresi (saniye).
`$last_played`	ISO8601	En son oynatma başlangıcı.

Pazaryeri

İki taraflı bir platformsanız ayarlayın.

Anahtar	Tür	Açıklama
`$seller_tier`	dize	Satıcı tarafındaki kademe slug'ı.
`$buyer_tier`	dize	Alıcı tarafı kademe slug’ı.
`$listings_count`	sayı	Kullanıcının sahip olduğu aktif ilanlar.
`$reviews_count`	sayı	Kullanıcının aldığı değerlendirmeler.
`$verified`	boolean	KYC durumu.

Sadakat

Etkileşim ve ödül programları için ayarlayın.

Anahtar	Tür	Açıklama
`$loyalty_points`	sayı	Kullanılabilir puan bakiyesi.
`$vip_level`	dize	VIP kademe slug'ı.
`$referral_count`	sayı	Bu kullanıcıya atfedilen başarılı yönlendirmeler.

İpucu

Aradığınız kalıp burada yoksa özel trait’ler için düz anahtarlar kullanın. Bunlar, profil sütunlarını doldurmadan dashboard’daki Custom Traits panelinde görünür. Yukarıdaki 5 dikey paket, en yaygın B2B yapıları için önerilmiş varsayımlardır; müşteriye özgü terimler (ör. shipping_plan) düz kalır.

Super-properties

Her gönderilen olaya otomatik eklenen, oturum bazlı anahtar/değer çiftleridir. identify() trait'lerinden farklıdır; trait'ler kimliği tanımlar, super-properties ise oturum bağlamını tanımlar: aktif A/B varyantı, derleme türü, izin verilmiş özellik bayrakları, affiliate ref. Yenilemeler arasında localStorage içinde saklanır; reset() sırasında temizlenir. Anahtar çakışmasında, track() üzerindeki olay düzeyindeki properties her zaman önceliklidir.

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

Isı haritaları

Isı haritası kaydı varsayılan olarak açıktır: tıklamalar ve kaydırma derinliği, ikisi de %100 örneklenir. Fare hareketi isteğe bağlıdır (yüksek hacimlidir; işe yarıyorsa sayfa bazında etkinleştirin).

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

Oturum yeniden oynatma

Oturum yeniden oynatma, rrweb DOM anlık görüntüsünü ve mutasyon akışını kaydeder; böylece pano, sayfayı olay iziyle birlikte ileri geri sarılabilen bir oturum olarak yeniden kurabilir. Bu, ekran videosu kaydı değil, DOM'un yeniden oluşturulmasıdır. Replay varsayılan olarak kapalı. Proje için Kontrol Paneli → Ayarlar → Oturum tekrarı altında etkinleştirin; uygulama kodunda değişiklik gerekmez. Etkinleştirildiğinde kaydedici, sürümü eşleşen ayrı bir parçadan sonradan indirilir.

Not

Tek doğruluk kaynağı panodur. Enable replay, Mask inputs, azami süre ve gelişmiş yakalama denetimlerini burada ayarlayın. captureOnCellular da iOS ve Android için aynı proje politikasında tutulur; tarayıcılar güvenilir bir Wi‑Fi / hücresel ağ sinyali sunmadığı için Web SDK bu yalnızca native ortama özgü kısıtı bildirir ve yok sayar.

Neler maskelenir

Replay güvenle açılacak şekilde tasarlanmıştır. Hassas içeriği koruyan üç katmanın tümü varsayılan olarak açıktır:

Girdi maskelemesi proje tarafından yönetilir — Dashboard’daki Girdileri maskele ayarı açıkken (varsayılan), girilen karakterler tarayıcıdan çıkmadan önce yıldızlarla değiştirilir. Bu ayarı yalnızca belirli ve düşük hassasiyetli bir ihtiyaç için kapatın; kimlik, kimlik doğrulama ve ödeme alanları yine maskelenir.
data-kixo-mask niteliği, bir öğeyi ve tüm alt ağacını engeller. Kişisel veya gizli içerik barındırabilecek herhangi bir kapsayıcıya ekleyin; replay’de bu alt ağacın metni veya DOM içeriği yerine bir yer tutucu görünür.
html
```
<div data-kixo-mask>
  
  
</div>
```
Hassas alanlar her zaman maskelenir — parola, kart numarası, CVV, SSN, secret veya token gibi görünen alanlar (type, name, id veya autocomplete değerine göre), projenin Girdileri maskele ayarı kapalı olsa bile maskelenir. Görünen metinler ve serileştirilmiş DOM öznitelikleri de yüklenmeden önce Kixo'nun PII temizleyicisinden geçer.

Veri toplama

SDK, entegrasyon ve proje ayarlarınızda etkin olan izleyicilerin yanı sıra uygulamanızın gönderdiği olay ve özellikleri de toplar.

Kayıtlar nereye gider

SDK, rrweb olaylarını boyutu sınırlı segmentler hâlinde gzip ile sıkıştırır, Kixo'dan projeye özel imzalı bir yükleme URL'si alır ve bu segmentleri doğrudan replay depolamasına yükler. Yeniden oluşturulan oturumu Tekrar Oynatma → Oturumlar altında açabilirsiniz; aynı oturumun analiz izine de bağlanır.

Not

Replay, planınıza bağlıdır. Yakalanan ve saklanan oturum sayısı proje planınıza bağlıdır; alt paketlerde Kixo yine de hafif oturum üst veri kaydeder, böylece oturum listelerde ve analizlerde görünür.

Özellik bayrakları

Bayrak değerlerini çalışma anında Kixo.getFeatureFlag() ile kontrol edin.

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

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

Gönderim ve çevrimdışı davranış

SDK, olayları yerelde kuyruğa alır, toplu gönderir ve geçici hataları artan bekleme süreleriyle yeniden dener. Toplama proje ayarlarından duraklatılırsa, yeniden etkinleştirilene kadar yeni olaylar gönderilmez.

Tanılama

Salt okunur sağlık özeti — geliştirici araçlarında "etkinliklerim neden akmıyor?" sorusunu ayıklamak için kullanışlıdır.

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