Error Handling

Tangani error dengan baik di lingkungan produksi untuk mencegah kegagalan yang tidak terlihat. Ketika sebuah pemanggilan seperti getResult() gagal, SDK melempar TracioError — sebuah subclass Error dengan field code yang dapat dibaca oleh mesin.

Menangkap error

Bungkus await tracio.getResult() dengan try/catch dan persempit nilai yang dilempar menggunakan isTracioError(), lalu bercabang berdasarkan error.code:

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

Callback onError

Agent dimuat secara asinkron di latar belakang. Jika pemuatan gagal sebelum Anda sempat memanggil getResult(), kegagalan tersebut disampaikan melalui callback onError. Daftarkan callback ini tepat setelah init():

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

Error yang sama tetap dapat diamati melalui getResult() — Anda dapat menggunakan salah satu dari kedua kanal tersebut.

Kode error

Setiap TracioError membawa code bertipe TracioErrorCode. Getter retryable (dan helper isRetryableError()) melaporkan apakah percobaan baru mungkin berhasil.

Code	Arti	Retryable
`invalid_config`	Konfigurasi yang diteruskan ke `Tracio.init()` tidak valid	Tidak
`multiple_keys`	Lebih dari satu public key digunakan pada halaman yang sama	Tidak
`non_browser`	`getResult()` di-await di luar browser (mis. di server)	Tidak
`load_failed`	Skrip agent gagal dimuat	Ya
`blocked`	Skrip diblokir (ad blocker atau CSP)	Ya
`script_error`	Skrip yang dimuat melempar error saat inisialisasi	Ya
`network`	Kegagalan jaringan/transport saat menjangkau API	Ya
`timeout`	Pemanggilan melampaui anggaran `timeoutMs` yang dikonfigurasi	Ya
`server`	Edge/server mengembalikan kegagalan upstream	Ya
`destroyed`	Instance dihancurkan (melalui `destroy()`) sebelum pemanggilan	Tidak

Kode terminal (invalid_config, multiple_keys, non_browser, destroyed) menandakan masalah konfigurasi, penggunaan, atau siklus hidup — perbaiki pemanggil atau panggil Tracio.init() kembali. Kode retryable bersifat sementara dan percobaan baru mungkin berhasil.

Strategi retry

Untuk error yang retryable, ulangi dengan backoff terhadap percobaan baru alih-alih meng-await ulang promise yang sama yang sudah ditolak:

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

Menangkap error

Bungkus await tracio.getResult() dengan try/catch dan persempit nilai yang dilempar menggunakan isTracioError(), lalu bercabang berdasarkan error.code:

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

Callback onError

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

Error yang sama tetap dapat diamati melalui getResult() — Anda dapat menggunakan salah satu dari kedua kanal tersebut.

Kode error

Setiap TracioError membawa code bertipe TracioErrorCode. Getter retryable (dan helper isRetryableError()) melaporkan apakah percobaan baru mungkin berhasil.

Code

Arti

Retryable

invalid_config

Konfigurasi yang diteruskan ke Tracio.init() tidak valid

Tidak

multiple_keys

Lebih dari satu public key digunakan pada halaman yang sama

Tidak

non_browser

getResult() di-await di luar browser (mis. di server)

Tidak

load_failed

Skrip agent gagal dimuat

blocked

Skrip diblokir (ad blocker atau CSP)

script_error

Skrip yang dimuat melempar error saat inisialisasi

network

Kegagalan jaringan/transport saat menjangkau API

timeout

Pemanggilan melampaui anggaran timeoutMs yang dikonfigurasi

server

Edge/server mengembalikan kegagalan upstream

destroyed

Instance dihancurkan (melalui destroy()) sebelum pemanggilan

Tidak

Strategi retry

Untuk error yang retryable, ulangi dengan backoff terhadap percobaan baru alih-alih meng-await ulang promise yang sama yang sudah ditolak:

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