JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk), tarayıcı sinyallerini toplar ve ziyaretçi tanımlama ile bot tespiti için TRACIO buluta gönderir. Hafiftir, engellemez ve tüm modern tarayıcılarla uyumludur.

Kurulum

npm install @tracio/sdk

Paket, eksiksiz TypeScript türleriyle birlikte ESM, CJS ve IIFE derlemeleri sunar.

CDN

TRACIO'yu bir bundler olmadan CDN üzerinden kullanmanın iki yolu vardır.

Edge betiği (otomatik başlatma)

Edge betiği, k sorgu parametresindeki public key'i kullanarak kendini otomatik olarak başlatır. JavaScript gerektirmez:

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

npm paketi (IIFE global)

Yayımlanan npm paketini unpkg veya jsDelivr üzerinden de yükleyebilirsiniz. Bir TracioSDK global'i sağlar. Bir sürüme sabitleyin:

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

Başlatma

Tracio.init(config)

SDK'yı başlatır ve senkron olarak bir TracioInstance döndürür. Agent arka planda yüklenir; örnek metotları, agent hazır olduğunda çözülür.

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

Tracio.init() farklı bir public key ile birden fazla kez çağrılırsa bir multiple_keys hatası fırlatır.

Tanımlama

tracio.getVisitorId()

Kararlı ziyaretçi tanımlayıcısına çözülen bir Promise<string> döndürür.

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Ziyaretçi kimliği ve bot tespiti sonucuyla birlikte bir Promise<TracioResult> döndürür.

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

Yaşam Döngüsü Geri Çağırmaları

tracio.onReady(cb)

Agent yüklendikten ve bir sonuç ürettikten sonra bir kez çağrılır.

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

SDK bir hatayla karşılaştığında çağrılır.

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Örneği söker ve kaynakları serbest bırakır. Sonraki çağrılar bir destroyed hatasıyla reddedilir.

tracio.destroy()

Hata İşleme

SDK, türü belirlenmiş bir code içeren TracioError örnekleri fırlatır. Dallanmak için isTracioError ve isRetryableError yardımcılarını kullanın:

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

Hata Kodları

TracioErrorCode union'ı şunları kapsar:

load_failed, blocked, script_error, network, timeout ve server yeniden denenebilir; isRetryableError(error) bunlar için true döndürür.

Framework Entegrasyonu

React, Vue, Angular ve Svelte için, core SDK'yı elle bağlamak yerine özel framework paketlerini kullanın:

• @tracio/react
• @tracio/vue
• @tracio/angular
• @tracio/svelte

Her biri @tracio/sdk'yı sarar ve deyimsel ilkeller (provider'lar, plugin'ler, hook'lar, composable'lar ve service'ler) sunar. Framework'e özgü kod parçacıkları için SDK'lara genel bakış sayfasına bakın.

Performans Konuları

• Engellemeyen: Tracio.init() senkron olarak döner ve agent'ı arka planda yükler. Sayfa oluşturmayı engellemez.
• Tek istek: Her tanımlama için bir istek yapılır.
• Zaman aşımı: Tanımlama timeoutMs (varsayılan 15000 ms) ile sınırlıdır, böylece yavaş bir ağ kodunuzu asla süresiz olarak askıda bırakmaz.