Error Handling

Zpracovávejte chyby v produkci elegantně, abyste předešli tichým selháním. Když volání jako getResult() selže, SDK vyhodí TracioError — podtřídu Error se strojově čitelným polem code.

Zachytávání chyb

Obalte await tracio.getResult() do try/catch a zúžte vyhozenou hodnotu pomocí isTracioError(), poté větvěte podle 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 se načítá asynchronně na pozadí. Pokud načítání selže dříve, než vůbec zavoláte getResult(), je selhání doručeno prostřednictvím callbacku onError. Zaregistrujte jej hned po 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)
})

Tatáž chyba zůstává pozorovatelná prostřednictvím getResult() — můžete použít kterýkoli z kanálů.

Chybové kódy

Každý TracioError nese code typu TracioErrorCode. Getter retryable (a pomocná funkce isRetryableError()) uvádějí, zda může nový pokus uspět.

Code	Význam	Retryable
`invalid_config`	Konfigurace předaná do `Tracio.init()` je neplatná	Ne
`multiple_keys`	Na téže stránce byl použit více než jeden public key	Ne
`non_browser`	`getResult()` bylo awaitováno mimo prohlížeč (např. na serveru)	Ne
`load_failed`	Skript agenta se nepodařilo načíst	Ano
`blocked`	Skript byl zablokován (ad blocker nebo CSP)	Ano
`script_error`	Načtený skript vyhodil chybu při inicializaci	Ano
`network`	Selhání sítě/přenosu při dosahování API	Ano
`timeout`	Volání překročilo nakonfigurovaný rozpočet `timeoutMs`	Ano
`server`	Edge/server vrátil upstream selhání	Ano
`destroyed`	Instance byla před voláním zničena (přes `destroy()`)	Ne

Terminální kódy (invalid_config, multiple_keys, non_browser, destroyed) značí problém s konfigurací, použitím nebo životním cyklem — opravte volajícího nebo znovu zavolejte Tracio.init(). Retryable kódy jsou přechodné a nový pokus může uspět.

Strategie opakování

U retryable chyb opakujte s backoffem proti novému pokusu, místo abyste znovu awaitovali totéž odmítnuté promise:

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

Zachytávání chyb

Obalte await tracio.getResult() do try/catch a zúžte vyhozenou hodnotu pomocí isTracioError(), poté větvěte podle 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)
})

Tatáž chyba zůstává pozorovatelná prostřednictvím getResult() — můžete použít kterýkoli z kanálů.

Chybové kódy

Každý TracioError nese code typu TracioErrorCode. Getter retryable (a pomocná funkce isRetryableError()) uvádějí, zda může nový pokus uspět.

Code

Význam

Retryable

invalid_config

Konfigurace předaná do Tracio.init() je neplatná

multiple_keys

Na téže stránce byl použit více než jeden public key

non_browser

getResult() bylo awaitováno mimo prohlížeč (např. na serveru)

load_failed

Skript agenta se nepodařilo načíst

Ano

blocked

Skript byl zablokován (ad blocker nebo CSP)

Ano

script_error

Načtený skript vyhodil chybu při inicializaci

Ano

network

Selhání sítě/přenosu při dosahování API

Ano

timeout

Volání překročilo nakonfigurovaný rozpočet timeoutMs

Ano

server

Edge/server vrátil upstream selhání

Ano

destroyed

Instance byla před voláním zničena (přes destroy())

Strategie opakování

U retryable chyb opakujte s backoffem proti novému pokusu, místo abyste znovu awaitovali totéž odmítnuté promise:

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