エラーハンドリング

本番環境ではエラーを適切に処理し、サイレント障害を防ぎましょう。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() ヘルパー）は、再試行が成功する可能性があるかどうかを示します。

コード	意味	リトライ可能
`invalid_config`	`Tracio.init()` に渡された設定が無効です	いいえ
`multiple_keys`	同一ページで複数の公開鍵が使用されました	いいえ
`non_browser`	`getResult()` がブラウザ外で（例: サーバー上で）awaitされました	いいえ
`load_failed`	エージェントスクリプトの読み込みに失敗しました	はい
`blocked`	スクリプトがブロックされました（広告ブロッカーまたはCSP）	はい
`script_error`	読み込まれたスクリプトが初期化中にスローしました	はい
`network`	APIへの到達時にネットワーク/トランスポート障害が発生しました	はい
`timeout`	呼び出しが設定された `timeoutMs` の予算を超過しました	はい
`server`	エッジ/サーバーが上流の障害を返しました	はい
`destroyed`	呼び出し前にインスタンスが（`destroy()` により）破棄されました	いいえ

終端コード（invalid_config、multiple_keys、non_browser、destroyed）は、設定、使用方法、またはライフサイクルの問題を示します — 呼び出し側を修正するか、Tracio.init() を再度呼び出してください。リトライ可能なコードは一時的なものであり、再試行が成功する可能性があります。

リトライ戦略

リトライ可能なエラーの場合は、同じ拒否された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() を通じても引き続き観測できます — どちらのチャネルを使っても構いません。

エラーコード

コード

意味

リトライ可能

invalid_config

Tracio.init() に渡された設定が無効です

いいえ

multiple_keys

同一ページで複数の公開鍵が使用されました

いいえ

non_browser

getResult() がブラウザ外で（例: サーバー上で）awaitされました

いいえ

load_failed

エージェントスクリプトの読み込みに失敗しました

はい

blocked

スクリプトがブロックされました（広告ブロッカーまたはCSP）

はい

script_error

読み込まれたスクリプトが初期化中にスローしました

はい

network

APIへの到達時にネットワーク/トランスポート障害が発生しました

はい

timeout

呼び出しが設定された timeoutMs の予算を超過しました

はい

server

エッジ/サーバーが上流の障害を返しました

はい

destroyed

呼び出し前にインスタンスが（destroy() により）破棄されました

いいえ

リトライ戦略

リトライ可能なエラーの場合は、同じ拒否された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))
    }
  }
}