오류 처리

무음(silent) 실패를 방지하려면 프로덕션에서 오류를 우아하게 처리하세요. getResult()와 같은 호출이 실패하면 SDK는 TracioError를 던집니다 — 기계가 판독할 수 있는 code 필드를 가진 Error 하위 클래스입니다.

오류 잡기

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는 TracioErrorCode 타입의 code를 갖습니다. retryable 게터(및 isRetryableError() 헬퍼)는 새로운 시도가 성공할 수 있는지 여부를 알려줍니다.

Code	의미	Retryable
`invalid_config`	`Tracio.init()`에 전달된 구성이 유효하지 않음	아니오
`multiple_keys`	동일한 페이지에서 둘 이상의 public key가 사용됨	아니오
`non_browser`	`getResult()`가 브라우저 밖에서 await됨(예: 서버에서)	아니오
`load_failed`	에이전트 스크립트를 로드하지 못함	예
`blocked`	스크립트가 차단됨(광고 차단기 또는 CSP)	예
`script_error`	로드된 스크립트가 초기화 중에 오류를 던짐	예
`network`	API에 도달하는 과정에서의 네트워크/전송 실패	예
`timeout`	호출이 구성된 `timeoutMs` 예산을 초과함	예
`server`	엣지/서버가 업스트림 실패를 반환함	예
`destroyed`	호출 전에 인스턴스가 (`destroy()`로) 파괴됨	아니오

종단(terminal) 코드(invalid_config, multiple_keys, non_browser, destroyed)는 구성, 사용법 또는 수명 주기 문제를 나타냅니다 — 호출자를 수정하거나 Tracio.init()을 다시 호출하세요. 재시도 가능(retryable) 코드는 일시적이며, 새로운 시도가 성공할 수 있습니다.

재시도 전략

재시도 가능한 오류의 경우, 동일하게 거부된(rejected) promise를 다시 await하지 말고 새로운 시도에 대해 백오프를 적용하여 재시도하세요:

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

오류 잡기

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 콜백

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()를 통해서도 계속 관찰할 수 있습니다 — 두 채널 중 어느 쪽이든 사용할 수 있습니다.

오류 코드

Code

의미

Retryable

invalid_config

Tracio.init()에 전달된 구성이 유효하지 않음

아니오

multiple_keys

동일한 페이지에서 둘 이상의 public key가 사용됨

아니오

non_browser

getResult()가 브라우저 밖에서 await됨(예: 서버에서)

아니오

load_failed

에이전트 스크립트를 로드하지 못함

예

blocked

스크립트가 차단됨(광고 차단기 또는 CSP)

예

script_error

로드된 스크립트가 초기화 중에 오류를 던짐

예

network

API에 도달하는 과정에서의 네트워크/전송 실패

예

timeout

호출이 구성된 timeoutMs 예산을 초과함

예

server

엣지/서버가 업스트림 실패를 반환함

예

destroyed

호출 전에 인스턴스가 (destroy()로) 파괴됨

아니오

재시도 전략

재시도 가능한 오류의 경우, 동일하게 거부된(rejected) promise를 다시 await하지 말고 새로운 시도에 대해 백오프를 적용하여 재시도하세요:

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