Obsługa błędów

Obsługuj błędy w środowisku produkcyjnym w przemyślany sposób, aby zapobiec cichym awariom. Gdy wywołanie takie jak getResult() zakończy się niepowodzeniem, SDK zgłasza TracioError — podklasę Error z polem code czytelnym maszynowo.

Przechwytywanie błędów

Otocz await tracio.getResult() blokiem try/catch i zawęź zgłoszoną wartość za pomocą isTracioError(), a następnie rozgałęź według 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 ładuje się asynchronicznie w tle. Jeśli ładowanie zakończy się niepowodzeniem, zanim w ogóle wywołasz getResult(), błąd zostanie dostarczony przez callback onError. Zarejestruj go bezpośrednio 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)
})

Ten sam błąd pozostaje obserwowalny przez getResult() — możesz korzystać z dowolnego z tych kanałów.

Kody błędów

Każdy TracioError niesie code typu TracioErrorCode. Getter retryable (oraz funkcja pomocnicza isRetryableError()) informują, czy ponowna próba może się powieść.

Code	Znaczenie	Retryable
`invalid_config`	Konfiguracja przekazana do `Tracio.init()` jest nieprawidłowa	Nie
`multiple_keys`	Na tej samej stronie użyto więcej niż jednego klucza publicznego	Nie
`non_browser`	Na `getResult()` oczekiwano poza przeglądarką (np. na serwerze)	Nie
`load_failed`	Nie udało się załadować skryptu agenta	Tak
`blocked`	Skrypt został zablokowany (ad blocker lub CSP)	Tak
`script_error`	Załadowany skrypt zgłosił błąd podczas inicjalizacji	Tak
`network`	Błąd sieci/transportu przy łączeniu z API	Tak
`timeout`	Wywołanie przekroczyło skonfigurowany budżet `timeoutMs`	Tak
`server`	Edge/serwer zwrócił błąd upstream	Tak
`destroyed`	Instancja została zniszczona (przez `destroy()`) przed wywołaniem	Nie

Kody terminalne (invalid_config, multiple_keys, non_browser, destroyed) wskazują na problem z konfiguracją, sposobem użycia lub cyklem życia — popraw kod wywołujący albo wywołaj Tracio.init() ponownie. Kody retryable są przejściowe i ponowna próba może się powieść.

Strategia ponawiania

W przypadku błędów retryable ponawiaj z backoffem, wykonując nową próbę, zamiast ponownie czekać na to samo odrzucone 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))
    }
  }
}

Przechwytywanie błędów

Otocz await tracio.getResult() blokiem try/catch i zawęź zgłoszoną wartość za pomocą isTracioError(), a następnie rozgałęź według 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)
})

Ten sam błąd pozostaje obserwowalny przez getResult() — możesz korzystać z dowolnego z tych kanałów.

Kody błędów

Każdy TracioError niesie code typu TracioErrorCode. Getter retryable (oraz funkcja pomocnicza isRetryableError()) informują, czy ponowna próba może się powieść.

Code

Znaczenie

Retryable

invalid_config

Konfiguracja przekazana do Tracio.init() jest nieprawidłowa

Nie

multiple_keys

Na tej samej stronie użyto więcej niż jednego klucza publicznego

Nie

non_browser

Na getResult() oczekiwano poza przeglądarką (np. na serwerze)

Nie

load_failed

Nie udało się załadować skryptu agenta

Tak

blocked

Skrypt został zablokowany (ad blocker lub CSP)

Tak

script_error

Załadowany skrypt zgłosił błąd podczas inicjalizacji

Tak

network

Błąd sieci/transportu przy łączeniu z API

Tak

timeout

Wywołanie przekroczyło skonfigurowany budżet timeoutMs

Tak

server

Edge/serwer zwrócił błąd upstream

Tak

destroyed

Instancja została zniszczona (przez destroy()) przed wywołaniem

Nie

Strategia ponawiania

W przypadku błędów retryable ponawiaj z backoffem, wykonując nową próbę, zamiast ponownie czekać na to samo odrzucone 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))
    }
  }
}