Hata Yönetimi

Sessiz hataları önlemek için üretim ortamında hataları düzgün bir şekilde ele alın. getResult() gibi bir çağrı başarısız olduğunda, SDK bir TracioError fırlatır — makine tarafından okunabilir bir code alanına sahip bir Error alt sınıfı.

Hataları yakalama

await tracio.getResult() çağrısını bir try/catch içine alın, fırlatılan değeri isTracioError() ile daraltın ve ardından error.code üzerinden dallanın:

TypeScript

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

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

try {
  const result = await tracio.getResult()
  console.log(result.visitorId, result.bot.detected)
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // Transient failure (network, timeout, blocked script, upstream) —
      // a fresh attempt may succeed.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Terminal failure (bad config, misuse, destroyed instance) —
      // fix the caller; retrying the same call will not help.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

onError geri çağırması

Agent, arka planda asenkron olarak yüklenir. Yükleme, siz getResult() çağrısını hiç yapmadan önce başarısız olursa, hata onError geri çağırması aracılığıyla iletilir. Onu init() çağrısının hemen ardından kaydedin:

TypeScript

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

tracio.onError((error) => {
  // Same TracioError instance you would catch from getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

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

Aynı hata getResult() aracılığıyla gözlemlenebilir olmaya devam eder — her iki kanalı da kullanabilirsiniz.

Hata kodları

Her TracioError, TracioErrorCode türünde bir code taşır. retryable getter'ı (ve isRetryableError() yardımcı fonksiyonu) yeni bir denemenin başarılı olup olamayacağını bildirir.

Kod	Anlamı	Yeniden denenebilir
`invalid_config`	`Tracio.init()` çağrısına geçirilen yapılandırma geçersiz	Hayır
`multiple_keys`	Aynı sayfada birden fazla public key kullanıldı	Hayır
`non_browser`	`getResult()` bir tarayıcı dışında await edildi (örn. sunucuda)	Hayır
`load_failed`	Agent betiği yüklenemedi	Evet
`blocked`	Betik engellendi (reklam engelleyici veya CSP)	Evet
`script_error`	Yüklenen betik başlatılırken bir hata fırlattı	Evet
`network`	API'ye erişirken ağ/aktarım hatası	Evet
`timeout`	Çağrı, yapılandırılan `timeoutMs` bütçesini aştı	Evet
`server`	Edge/sunucu bir upstream hatası döndürdü	Evet
`destroyed`	Örnek, çağrıdan önce (`destroy()` ile) yok edildi	Hayır

Terminal kodlar (invalid_config, multiple_keys, non_browser, destroyed) bir yapılandırma, kullanım veya yaşam döngüsü sorununa işaret eder — çağıranı düzeltin veya Tracio.init() çağrısını yeniden yapın. Retryable kodlar geçicidir ve yeni bir deneme başarılı olabilir.

Yeniden deneme stratejisi

Retryable hatalar için, aynı reddedilmiş promise'i yeniden await etmek yerine geri çekilme (backoff) ile yeni bir denemeye karşı yeniden deneyin:

TypeScript

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

async function identifyWithRetry(maxAttempts = 3) {
  let attempt = 0
  while (true) {
    const tracio = Tracio.init({ publicKey: "5ca175fc..." })
    try {
      return await tracio.getResult()
    } catch (error) {
      attempt++
      // Tear down before retrying: init() returns the cached instance for the
      // same key, and getResult() caches its (rejected) promise — so a genuine
      // fresh attempt requires destroy() first.
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}

Hataları yakalama

await tracio.getResult() çağrısını bir try/catch içine alın, fırlatılan değeri isTracioError() ile daraltın ve ardından error.code üzerinden dallanın:

TypeScript

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

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

try {
  const result = await tracio.getResult()
  console.log(result.visitorId, result.bot.detected)
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // Transient failure (network, timeout, blocked script, upstream) —
      // a fresh attempt may succeed.
      console.warn(`Retryable TRACIO error: ${error.code}`)
    } else {
      // Terminal failure (bad config, misuse, destroyed instance) —
      // fix the caller; retrying the same call will not help.
      console.error(`Terminal TRACIO error: ${error.code} — ${error.message}`)
    }
  } else {
    console.error("Unexpected error:", error)
  }
}

onError geri çağırması

TypeScript

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

tracio.onError((error) => {
  // Same TracioError instance you would catch from getResult().
  console.warn(`TRACIO failed to initialize: ${error.code}`)
})

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

Aynı hata getResult() aracılığıyla gözlemlenebilir olmaya devam eder — her iki kanalı da kullanabilirsiniz.

Hata kodları

Her TracioError, TracioErrorCode türünde bir code taşır. retryable getter'ı (ve isRetryableError() yardımcı fonksiyonu) yeni bir denemenin başarılı olup olamayacağını bildirir.

Kod

Anlamı

Yeniden denenebilir

invalid_config

Tracio.init() çağrısına geçirilen yapılandırma geçersiz

Hayır

multiple_keys

Aynı sayfada birden fazla public key kullanıldı

Hayır

non_browser

getResult() bir tarayıcı dışında await edildi (örn. sunucuda)

Hayır

load_failed

Agent betiği yüklenemedi

Evet

blocked

Betik engellendi (reklam engelleyici veya CSP)

Evet

script_error

Yüklenen betik başlatılırken bir hata fırlattı

Evet

network

API'ye erişirken ağ/aktarım hatası

Evet

timeout

Çağrı, yapılandırılan timeoutMs bütçesini aştı

Evet

server

Edge/sunucu bir upstream hatası döndürdü

Evet

destroyed

Örnek, çağrıdan önce (destroy() ile) yok edildi

Hayır

Yeniden deneme stratejisi

Retryable hatalar için, aynı reddedilmiş promise'i yeniden await etmek yerine geri çekilme (backoff) ile yeni bir denemeye karşı yeniden deneyin:

TypeScript

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

async function identifyWithRetry(maxAttempts = 3) {
  let attempt = 0
  while (true) {
    const tracio = Tracio.init({ publicKey: "5ca175fc..." })
    try {
      return await tracio.getResult()
    } catch (error) {
      attempt++
      // Tear down before retrying: init() returns the cached instance for the
      // same key, and getResult() caches its (rejected) promise — so a genuine
      // fresh attempt requires destroy() first.
      tracio.destroy()
      if (!isRetryableError(error) || attempt >= maxAttempts) throw error
      await new Promise((r) => setTimeout(r, 2 ** attempt * 250))
    }
  }
}