JavaScript SDK

TRACIO JavaScript SDK（@tracio/sdk）は、ブラウザシグナルを収集し、訪問者識別とボット検知のためにそれらを TRACIO クラウドへ送信します。軽量でノンブロッキングであり、すべてのモダンブラウザと互換性があります。

インストール

bash

npm install @tracio/sdk

このパッケージは、完全なTypeScript型定義を備えた ESM、CJS、IIFE ビルドを同梱しています。

CDN

バンドラーなしで CDN から TRACIO を利用する方法が2つあります。

エッジスクリプト（自動初期化）

エッジスクリプトは、k クエリパラメータに含まれる公開鍵を用いて自動的に初期化します。JavaScript は不要です。

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

npm バンドル（IIFE グローバル）

公開されている npm バンドルを unpkg または jsDelivr から読み込むこともできます。これは TracioSDK グローバルを公開します。バージョンを固定してください。

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

初期化

Tracio.init(config)

SDK を初期化し、TracioInstance を同期的に返します。エージェントはバックグラウンドで読み込まれ、インスタンスのメソッドは準備が整い次第解決します。

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

オプション	型	デフォルト	説明
`publicKey`	`string`	必須	あなたの公開鍵。ダッシュボードからコピーしてください。
`region`	`"us" \| "eu"`	なし	任意のデータリージョン。未設定の場合、SDK は汎用の `https://edge.tracio.ai` エンドポイントを使用します（米国データレジデンシーは暗黙的に含みません）。`us` または `eu` を固定するには明示的に設定してください。
`endpoint`	`string`	自動	カスタムAPIエンドポイント（ファーストパーティプロキシ経由のエンドポイント用）。
`scriptUrl`	`string`	自動	エージェントスクリプトのカスタムURL（ファーストパーティプロキシ経由のエンドポイント用）。
`linkedId`	`string`	なし	この訪問者をあなたのシステム内のエンティティに紐付ける識別子。
`tag`	`string`	なし	後でフィルタリングするためにリクエストに添付される自由形式のラベル。
`debug`	`boolean`	`false`	詳細な診断情報をコンソールに記録します。
`timeoutMs`	`number`	`15000`	タイムアウトするまで結果を待つ時間。

異なる公開鍵で Tracio.init() を複数回呼び出すと、multiple_keys エラーがスローされます。

識別

tracio.getVisitorId()

安定した訪問者識別子に解決する Promise<string> を返します。

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

訪問者IDとボット検知結果を含む Promise<TracioResult> を返します。

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

ライフサイクルコールバック

tracio.onReady(cb)

エージェントが読み込まれて結果を生成した時点で呼び出されます。

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

SDK がエラーに遭遇したときに呼び出されます。

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

インスタンスを破棄してリソースを解放します。以降の呼び出しは destroyed エラーで拒否されます。

TypeScript

tracio.destroy()

エラー処理

SDK は、型付けされた code を持つ TracioError インスタンスをスローします。分岐には isTracioError および isRetryableError ヘルパーを使用してください。

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

エラーコード

TracioErrorCode ユニオンは次をカバーします。

コード	説明
`blocked`	リクエストがブロックされました（例: 広告ブロッカーによる）。
`destroyed`	呼び出しが完了する前にインスタンスが破棄されました。
`invalid_config`	構成が無効です（例: `publicKey` の欠落）。
`load_failed`	エージェントスクリプトの読み込みに失敗しました。
`multiple_keys`	競合する公開鍵で `Tracio.init()` が呼び出されました。
`network`	ネットワークリクエストが失敗しました。
`non_browser`	SDK がブラウザ環境の外で使用されました。
`script_error`	エージェントスクリプトが実行時にエラーを発生させました。
`server`	サーバーがエラーを返しました。
`timeout`	リクエストが `timeoutMs` を超過しました。

load_failed、blocked、script_error、network、timeout、server はリトライ可能です。isRetryableError(error) はこれらに対して true を返します。

フレームワーク統合

React、Vue、Angular、Svelte については、コアSDKを手作業で組み立てる代わりに、専用のフレームワークパッケージを使用してください。

各パッケージは @tracio/sdk をラップし、慣用的なプリミティブ（プロバイダー、プラグイン、フック、コンポーザブル、サービス）を公開します。フレームワークごとのスニペットについては SDK 概要を参照してください。

パフォーマンスに関する考慮事項

ノンブロッキング: Tracio.init() は同期的に返り、エージェントをバックグラウンドで読み込みます。ページのレンダリングをブロックしません。
単一リクエスト: 識別ごとに1回のリクエストが行われます。
タイムアウト: 識別は timeoutMs（デフォルト15000ms）で制限されるため、遅いネットワークがあなたのコードを無期限にハングさせることはありません。

JavaScript SDK

インストール

bash

npm install @tracio/sdk

このパッケージは、完全なTypeScript型定義を備えた ESM、CJS、IIFE ビルドを同梱しています。

CDN

バンドラーなしで CDN から TRACIO を利用する方法が2つあります。

エッジスクリプト（自動初期化）

エッジスクリプトは、k クエリパラメータに含まれる公開鍵を用いて自動的に初期化します。JavaScript は不要です。

HTML

<script src="https://edge.tracio.ai/s.js?k=PUBLIC_KEY" async></script>

npm バンドル（IIFE グローバル）

HTML

<script src="https://unpkg.com/@tracio/sdk@0.1.3/dist/index.min.js"></script>
<script>
  const tracio = TracioSDK.Tracio.init({ publicKey: "5ca175fc..." })
</script>

初期化

Tracio.init(config)

TypeScript

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

TracioConfig

TypeScript

interface TracioConfig {
  publicKey: string // required
  region?: "us" | "eu"
  endpoint?: string
  scriptUrl?: string
  linkedId?: string
  tag?: string
  debug?: boolean
  timeoutMs?: number // default 15000
}

オプション	型	デフォルト	説明
`publicKey`	`string`	必須	あなたの公開鍵。ダッシュボードからコピーしてください。
`region`	`"us" \| "eu"`	なし	任意のデータリージョン。未設定の場合、SDK は汎用の `https://edge.tracio.ai` エンドポイントを使用します（米国データレジデンシーは暗黙的に含みません）。`us` または `eu` を固定するには明示的に設定してください。
`endpoint`	`string`	自動	カスタムAPIエンドポイント（ファーストパーティプロキシ経由のエンドポイント用）。
`scriptUrl`	`string`	自動	エージェントスクリプトのカスタムURL（ファーストパーティプロキシ経由のエンドポイント用）。
`linkedId`	`string`	なし	この訪問者をあなたのシステム内のエンティティに紐付ける識別子。
`tag`	`string`	なし	後でフィルタリングするためにリクエストに添付される自由形式のラベル。
`debug`	`boolean`	`false`	詳細な診断情報をコンソールに記録します。
`timeoutMs`	`number`	`15000`	タイムアウトするまで結果を待つ時間。

異なる公開鍵で Tracio.init() を複数回呼び出すと、multiple_keys エラーがスローされます。

識別

tracio.getVisitorId()

安定した訪問者識別子に解決する Promise<string> を返します。

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

訪問者IDとボット検知結果を含む Promise<TracioResult> を返します。

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId)

if (result.bot.detected) {
  console.warn("bot, confidence:", result.bot.confidence)
}

TracioResult

TypeScript

interface TracioResult {
  visitorId: string
  bot: {
    detected: boolean
    confidence: number // 0-100
    reasons?: string[]
  }
}

ライフサイクルコールバック

tracio.onReady(cb)

エージェントが読み込まれて結果を生成した時点で呼び出されます。

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

SDK がエラーに遭遇したときに呼び出されます。

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

インスタンスを破棄してリソースを解放します。以降の呼び出しは destroyed エラーで拒否されます。

TypeScript

tracio.destroy()

エラー処理

TypeScript

import { Tracio, isTracioError, isRetryableError } from "@tracio/sdk"

const tracio = Tracio.init({ publicKey: "5ca175fc..." })

try {
  const result = await tracio.getResult()
} catch (error) {
  if (isTracioError(error)) {
    if (isRetryableError(error)) {
      // load_failed / blocked / script_error / network / timeout / server — safe to retry
    }
    console.error("TRACIO error:", error.code, error.message)
  } else {
    console.error("Unexpected error:", error)
  }
}

エラーコード

TracioErrorCode ユニオンは次をカバーします。

コード	説明
`blocked`	リクエストがブロックされました（例: 広告ブロッカーによる）。
`destroyed`	呼び出しが完了する前にインスタンスが破棄されました。
`invalid_config`	構成が無効です（例: `publicKey` の欠落）。
`load_failed`	エージェントスクリプトの読み込みに失敗しました。
`multiple_keys`	競合する公開鍵で `Tracio.init()` が呼び出されました。
`network`	ネットワークリクエストが失敗しました。
`non_browser`	SDK がブラウザ環境の外で使用されました。
`script_error`	エージェントスクリプトが実行時にエラーを発生させました。
`server`	サーバーがエラーを返しました。
`timeout`	リクエストが `timeoutMs` を超過しました。

load_failed、blocked、script_error、network、timeout、server はリトライ可能です。isRetryableError(error) はこれらに対して true を返します。

フレームワーク統合

React、Vue、Angular、Svelte については、コアSDKを手作業で組み立てる代わりに、専用のフレームワークパッケージを使用してください。

パフォーマンスに関する考慮事項

ノンブロッキング: Tracio.init() は同期的に返り、エージェントをバックグラウンドで読み込みます。ページのレンダリングをブロックしません。
単一リクエスト: 識別ごとに1回のリクエストが行われます。
タイムアウト: 識別は timeoutMs（デフォルト15000ms）で制限されるため、遅いネットワークがあなたのコードを無期限にハングさせることはありません。