Web SDK

Web SDK, tarayıcıda cihaz ve davranışsal telemetri toplar ve kimlik risk snapshot'ını sizin için ister. Headless'tır — monte edilecek bir widget, iframe veya UI yoktur. Onu script'lersiniz: bir client oluşturun, imzalı bir oturumu init() edin, ardından analyze() ve track() çağırın. Arka planda /identity/sdk/* endpoint'leri bir session token ile çağırır; secret key'iniz sayfaya asla girmez.

https://cdn.lunixi.com üzerinden yükleyin:

<script src="https://cdn.lunixi.com/lunixi-identity.min.js"></script>

Global Lunixi'dir. Kimlik doğrulama, backend'inizin ürettiği imzalı bir SDK session token ile yapılır — bkz. Kimlik Doğrulama.

Global API

Çağrı	Döner	Ne yapar
`Lunixi.configure(config)`	—	Sonradan oluşturulan her client'a uygulanan varsayılanları ayarlar. Opsiyonel.
`Lunixi.identity.createClient(config)`	client	Bir client'ı init etmeden oluşturur. `init()`'i kendiniz çağırırsınız.
`Lunixi.identity.init(config)`	`Promise<client>`	Kolaylık: bir client oluşturur ve `init()`'i bekler — init edilmiş bir client.

const client = await Lunixi.identity.init({
  sessionBootstrapUrl: '/lunixi/identity/session',
  subjectId: 'cus_8f2a9c',
  productContext: 'checkout',
});
const snapshot = await client.analyze();

Client metotları

Metot	Döner	Amaç
`init()`	`Promise<void>`	Bootstrap'i çalıştırır ve imzalı SDK session token'ı alır. analyze/track öncesi gereklidir.
`analyze()`	`Promise<snapshot>`	Mevcut oturum ve bağlam için senkron bir kimlik risk snapshot'ı ister.
`track(eventType, payload)`	`Promise<void>`	Davranışsal sinyali zenginleştirmek için tek bir etkileşim olayı gönderir.
`trackBatch(events)`	`Promise<void>`	Tek çağrıda bir olay dizisi gönderir.
`compatibility()`	`Promise<result>`	SDK/ortam yeteneğini ve politikasını bildirir — auth gerektirmez.
`getSession()`	session	Bellekte tutulan mevcut SDK oturumu (token, endpoint'ler).

analyze()

analyze() çekirdek çağrıdır: toplanan telemetriyi toplar, session token ile gönderir ve düz snapshot'a çözülür — identityRiskLevel, riskScore, alan-alan sinyaller, reasonCodes, findings. İhtiyacınız olan alanları okur ve kendi politikanızı uygularsınız.

const snapshot = await client.analyze();
if (snapshot.identityRiskLevel === 'high' || snapshot.identityRiskLevel === 'critical') {
  // kararınız — SDK sizin yerinize bloklamaz
}

track() ve trackBatch()

Olaylar, bir oturumun ömrü boyunca davranışsal sinyali besler (bir cüzdan transferi tıklaması, ulaşılan bir adım, odaklanılan bir alan). Olay tipi serbest bir string'dir — sabit bir enum yoktur; varsayılan tip sdk_event'tir.

await client.track('wallet_transfer_click', { amount: 25000, currency: 'TRY' });
 
await client.trackBatch([
  { type: 'step_reached', payload: { step: 'review' } },
  { type: 'field_focus',  payload: { field: 'iban' } },
]);

Yapılandırma

Config; configure, createClient veya init'e geçilir. Bir bootstrap kaynağı dışında tüm alanlar opsiyoneldir.

Bağlantı

Alan	Açıklama
`apiBaseUrl`	API host'unu geçersiz kılar. Varsayılan hosted gateway'dir (`https://api-gateway.lunixi.com`).
`platformBaseUrl`	Gateway ve platform trafiğini ayırıyorsanız platform host'unu geçersiz kılar.
`allowedOrigin`	Oturumun bağlandığı origin. Varsayılan `window.location.origin`'dir.

Oturum bootstrap'i (biri gerekli)

SDK asla bir anahtar tutmaz — imzalı bir oturumu backend'inizden şunlardan biriyle alır:

Alan	Açıklama
`sessionBootstrap(fn)`	SDK'nın, oturumu backend'inizden çekmek için çağırdığı bir async fonksiyon.
`sessionBootstrapUrl`	SDK'nın oturumu çektiği bir backend URL'si (`POST /identity/sdk/init`'in proxy'si).
`sessionData`	Sunucu tarafında zaten aldığınız ve doğrudan enjekte ettiğiniz bir oturum nesnesi.

Bkz. Kimlik Doğrulama › Bootstrap desenleri.

Kimlik & bağlam

Alan	Açıklama
`subjectId`	Kimi skorluyorsunuz (customer/user id'niz).
`paymentId` / `checkoutSessionId`	Analizi bir ödeme veya checkout oturumuna bağlayarak sonradan sorgulanabilir kılar.
`integrationMode`	SDK'nın akışınıza nasıl gömüldüğü.
`productContext`	İş bağlamı, ör. `checkout`, `login`, `signup`.
`payment`, `walletOperation`, `customer`, `account`	Skorlanan olayla ilgili yapılandırılmış iş bağlamı.

Telemetri

Alan	Açıklama
`device`, `telemetry`, `network`, `session`, `source`	SDK'nın topladığı ve/veya sizin tamamladığınız telemetri.
`metadata`	Analize yansıtılan serbest biçimli anahtar/değer verisi.

Dahili alanlar yanıttan soyulur ve public payload'un parçası değildir. Yalnızca yukarıdaki bağlamı sağlayın; dahili metadata anahtarlarına bağımlı olmayın.

Token rotasyonu

Session token kısa ömürlüdür. Bir çağrı yenilenmiş bir token döndürdüğünde SDK otomatik olarak ona geçer — token ömrünü kendiniz yönetmezsiniz. Oturumlar origin-bound'dur: bir origin için üretilen token başka yerde reddedilir.

Hata yönetimi — fail-open değil

⚠️

SDK fail-open değildir. init(), analyze() veya track() başarısız olursa throw eder veya reject olur — sessizce bir "geçti" döndürmez. Fallback sizindir: çağrıları try/catch içine alın ve snapshot yokken akışınızın nasıl davranacağına karar verin (devam et, sürtünme ekle veya beklet).

try {
  const client = await Lunixi.identity.init({ sessionBootstrapUrl: '/lunixi/identity/session' });
  const snapshot = await client.analyze();
  // snapshot.identityRiskLevel üzerinde politikanızı uygulayın
} catch (err) {
  // kimlik sinyali yokken kararınız
}

Tek nazik degradasyon boyuttur: 48 KB'yi aşan bir payload reddedilmek yerine truncate edilir ve yanıt __sdkTruncated: true ile işaretlenir; böylece telemetrinin kırpıldığını bilirsiniz.

Eşdeğer HTTP çağrıları

SDK, /identity/sdk/* endpoint'ler üzerinde ince bir client'tır. Her metot, session token'ı Authorization: Bearer <token> olarak taşıyan bir isteğe karşılık gelir — token yalnızca header'dadır, asla gövdede değil.

SDK metodu	HTTP çağrısı
`init()`	`POST /identity/sdk/init` (backend'iniz üzerinden, publishable key) → session token
`analyze()`	`POST /identity/sdk/live-sessions/analyze-sync`
`track(...)`	`POST /identity/sdk/live-sessions/event`
`trackBatch(...)`	`POST /identity/sdk/live-sessions/events/batch`
`compatibility()`	`POST /identity/sdk/compatibility` (public)

# analyze()'in gönderdiği, elle:
curl -X POST "https://api-gateway.lunixi.com/api/v1/identity/sdk/live-sessions/analyze-sync" \
  -H "Authorization: Bearer <sdk-session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subjectId": "cus_8f2a9c",
    "productContext": "checkout"
  }'

Bir tarayıcı oturumu yerine bir backend olayını mı skorluyorsunuz? SDK'yı atlayın ve sunucu tarafı endpoint'leri secret key'inizle çağırın — bkz. Sunucu API & Sorgular.

Sonraki adımlar

Risk Snapshot — analyze()'in döndürdüğü her alan.
Kimlik Doğrulama — publishable key, session token ve bootstrap detaylı.
Cihaz & Süreklilik · Bot & Otomasyon — SDK'nın beslediği sinyaller.

Kimlik Doğrulama Risk Snapshot