クイックスタート

このガイドでは、TRACIOをアプリケーションに統合する手順を説明します。クライアントSDKをインストールし、公開鍵で初期化し、最初の訪問者識別結果を読み取ります。

ステップ1: SDKのインストール

お好みのパッケージマネージャーを使用してTRACIO SDKをインストールします:

bash

npm install @tracio/sdk

または pnpm で:

bash

pnpm add @tracio/sdk

または yarn で:

bash

yarn add @tracio/sdk

ビルド不要のCDNスニペット

バンドラーを使用しない場合は、エッジのスクリプトタグをページに配置します。kクエリパラメータの公開鍵で自動的に初期化されます:

HTML

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

ステップ2: SDKの初期化

Tracioをインポートし、公開鍵を指定してTracio.init()を呼び出します。これはただちにTracioInstanceを返します。基盤となるエージェントはバックグラウンドで読み込まれます。

TypeScript

import { Tracio } from "@tracio/sdk"

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

公開鍵はクライアント側のコードに含めても安全です。ダッシュボードのAPI Keysで確認できます。

設定オプション

Tracio.init()はTracioConfigオブジェクトを受け取ります:

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

ステップ3: 訪問者IDの取得

tracio.getVisitorId()を呼び出して、安定した訪問者識別子を取得します。これは非同期処理です。

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

ステップ4: 完全な結果の読み取り

tracio.getResult()を呼び出して、ボット検知を含む完全な識別結果を取得します。

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

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

結果は次の形式です:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

ステップ5: ライフサイクルとエラー

ライフサイクルコールバックを使用して、エージェントの準備が完了したときや何らかの失敗が発生したときに対応し、destroy()でインスタンスを破棄します:

TypeScript

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

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

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

// later, when you no longer need it
tracio.destroy()

エラーコードの完全な一覧と再試行ヘルパーについては、Error Handlingを参照してください。

一般的な統合パターン

ログイン保護

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

決済不正防止

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

次のステップ

How It Works — シグナル収集と識別のパイプラインを理解する
JavaScript SDK Reference — SDK APIの完全なドキュメント
Webhooks — 識別イベントをサーバーでリアルタイムに受信する
Bot Detection — 自動化検知の詳細

クイックスタート

ステップ1: SDKのインストール

お好みのパッケージマネージャーを使用してTRACIO SDKをインストールします:

bash

npm install @tracio/sdk

または pnpm で:

bash

pnpm add @tracio/sdk

または yarn で:

bash

yarn add @tracio/sdk

ビルド不要のCDNスニペット

バンドラーを使用しない場合は、エッジのスクリプトタグをページに配置します。kクエリパラメータの公開鍵で自動的に初期化されます:

HTML

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

ステップ2: SDKの初期化

TypeScript

import { Tracio } from "@tracio/sdk"

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

公開鍵はクライアント側のコードに含めても安全です。ダッシュボードのAPI Keysで確認できます。

設定オプション

Tracio.init()はTracioConfigオブジェクトを受け取ります:

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

ステップ3: 訪問者IDの取得

tracio.getVisitorId()を呼び出して、安定した訪問者識別子を取得します。これは非同期処理です。

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

ステップ4: 完全な結果の読み取り

tracio.getResult()を呼び出して、ボット検知を含む完全な識別結果を取得します。

TypeScript

const result = await tracio.getResult()

console.log(result.visitorId) // "X7fh2Hg9LkMn3pQr"

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

結果は次の形式です:

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr",
  bot: {
    detected: false,
    confidence: 2,        // 0-100
    reasons: [],
  },
}

ステップ5: ライフサイクルとエラー

TypeScript

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

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

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

// later, when you no longer need it
tracio.destroy()

エラーコードの完全な一覧と再試行ヘルパーについては、Error Handlingを参照してください。

一般的な統合パターン

ログイン保護

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function handleLogin(email: string, password: string) {
  const visitorId = await tracio.getVisitorId()

  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify({ email, password, visitorId }),
  })

  return response.json()
}

決済不正防止

TypeScript

import { Tracio } from "@tracio/sdk"

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

async function processPayment(paymentData: PaymentData) {
  const result = await tracio.getResult()

  if (result.bot.detected) {
    throw new Error("Automated client detected")
  }

  const response = await fetch("/api/payment", {
    method: "POST",
    body: JSON.stringify({ ...paymentData, visitorId: result.visitorId }),
  })

  return response.json()
}

次のステップ

How It Works — シグナル収集と識別のパイプラインを理解する
JavaScript SDK Reference — SDK APIの完全なドキュメント
Webhooks — 識別イベントをサーバーでリアルタイムに受信する
Bot Detection — 自動化検知の詳細