Error Handling

Коректно обробляйте помилки у production, щоб уникнути тихих збоїв. Коли виклик на кшталт getResult() зазнає невдачі, SDK кидає TracioError — підклас Error з машинозчитуваним полем code.

Перехоплення помилок

Оберніть await tracio.getResult() у try/catch і звузьте кинуте значення за допомогою isTracioError(), після чого розгалужуйтеся за 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)
  }
}

Колбек onError

Агент завантажується асинхронно у фоні. Якщо завантаження зазнає невдачі ще до того, як ви взагалі викличете getResult(), збій доставляється через колбек onError. Реєструйте його одразу після 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)
})

Та сама помилка залишається доступною для спостереження через getResult() — ви можете використовувати будь-який із каналів.

Коди помилок

Кожен TracioError несе code типу TracioErrorCode. Ґеттер retryable (і допоміжна функція isRetryableError()) повідомляють, чи може нова спроба виявитися успішною.

Code	Значення	Retryable
`invalid_config`	Конфігурація, передана в `Tracio.init()`, недійсна	Ні
`multiple_keys`	На одній сторінці використано більш ніж один публічний ключ	Ні
`non_browser`	`getResult()` очікувано (await) поза браузером (напр. на сервері)	Ні
`load_failed`	Скрипт агента не вдалося завантажити	Так
`blocked`	Скрипт було заблоковано (блокувальник реклами або CSP)	Так
`script_error`	Завантажений скрипт кинув помилку під час ініціалізації	Так
`network`	Збій мережі/транспорту при зверненні до API	Так
`timeout`	Виклик перевищив налаштований бюджет `timeoutMs`	Так
`server`	Edge/сервер повернув upstream-помилку	Так
`destroyed`	Екземпляр було знищено (через `destroy()`) до виклику	Ні

Термінальні коди (invalid_config, multiple_keys, non_browser, destroyed) вказують на проблему конфігурації, використання або життєвого циклу — виправте код-виклик або викличте Tracio.init() знову. Retryable-коди є тимчасовими, і нова спроба може виявитися успішною.

Стратегія повторних спроб

Для retryable-помилок повторюйте з backoff у межах нової спроби, замість повторного очікування (await) того самого відхиленого 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))
    }
  }
}

Error Handling

Перехоплення помилок

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

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

Коди помилок

Code

Значення

Retryable

invalid_config

Конфігурація, передана в Tracio.init(), недійсна

Ні

multiple_keys

На одній сторінці використано більш ніж один публічний ключ

Ні

non_browser

getResult() очікувано (await) поза браузером (напр. на сервері)

Ні

load_failed

Скрипт агента не вдалося завантажити

Так

blocked

Скрипт було заблоковано (блокувальник реклами або CSP)

Так

script_error

Завантажений скрипт кинув помилку під час ініціалізації

Так

network

Збій мережі/транспорту при зверненні до API

Так

timeout

Виклик перевищив налаштований бюджет timeoutMs

Так

server

Edge/сервер повернув upstream-помилку

Так

destroyed

Екземпляр було знищено (через destroy()) до виклику

Ні

Стратегія повторних спроб

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