React SDK

@tracio/reactパッケージはコアの@tracio/sdkをラップし、Reactらしいプリミティブを提供します。エージェントをマウントするproviderと、読み込み状態およびエラー状態とともに訪問者IDと識別結果を渡すフックです。

インストール

bash

npm install @tracio/react @tracio/sdk

react（18または19）はpeer dependencyであり、アプリにすでにインストールされていることが前提です。

セットアップ

アプリケーションを<TracioProvider>でラップします。初回レンダリング時にTRACIOエージェントをマウントし、providerがアンマウントされると自動的にtracio.destroy()を呼び出します。

tsx

import { TracioProvider } from "@tracio/react"

function Root() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <App />
    </TracioProvider>
  )
}

Providerのprops

Prop	型	説明
`publicKey`	`string`	公開鍵。ダッシュボードからコピーします。
`config`	`TracioConfig`	完全な設定オブジェクト。下記のフラットなスカラーpropsより優先されます。
`endpoint`	`string`	カスタムAPIエンドポイント（ファーストパーティでプロキシされたエンドポイント用）。
`scriptUrl`	`string`	エージェントスクリプトのカスタムURL（ファーストパーティでプロキシされたエンドポイント用）。
`debug`	`boolean`	詳細な診断情報をコンソールに出力します。
`timeoutMs`	`number`	タイムアウトするまで結果を待つ時間（デフォルト15000）。
`children`	`ReactNode`	必須。ラップするReactのサブツリー。

publicKeyとフラットなスカラーを渡すか、完全なconfigオブジェクトを渡します。両方が指定された場合はconfigが優先されます。

フック

useVisitorId()

安定した訪問者識別子を、読み込み状態およびエラー状態とともに返します。

tsx

const { data, isLoading, error, isFetched, getId } = useVisitorId()
// data: string | undefined — the visitorId

getId()は訪問者IDを命令的に再取得します。

useTracioResult(opts?)

完全なTracioResult（訪問者IDとボット検知）を返します。

tsx

const { data, isLoading, error, isFetched, getData } = useTracioResult()
// data: TracioResult | undefined

opts.immediateのデフォルトはtrueです。{ immediate: false }を渡すと、自分でgetData()を呼び出すまで取得を延期できます。同意ゲートの背後で便利です:

tsx

const { data, getData } = useTracioResult({ immediate: false })

function onConsent() {
  getData() // identify only after the user opts in
}

useTracio()

高度な用途のために基盤となるインスタンスを返すエスケープハッチです。

tsx

const { tracio } = useTracio()

完全な例

tsx

import { TracioProvider, useVisitorId } from "@tracio/react"
function App() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <Page />
    </TracioProvider>
  )
}
function Page() {
  const { data: visitorId, isLoading, error } = useVisitorId()
  if (isLoading) return <span>Loading…</span>
  if (error) return <span>Error: {error.message}</span>
  return <span>Visitor: {visitorId}</span>
}

次のステップ

JavaScript SDK Reference — フックが構築される基盤となるコアの@tracio/sdk API
Error Handling — エラーコードと再試行戦略
SDKs overview — すべてのフレームワークパッケージを一覧で