JavaScript SDK

TRACIO JavaScript SDK（@tracio/sdk）采集浏览器信号并将其发送到 TRACIO 云端，用于访客识别和机器人检测。它轻量、非阻塞，并兼容所有现代浏览器。

安装

bash

npm install @tracio/sdk

该软件包提供 ESM、CJS 和 IIFE 构建版本，并附带完整的 TypeScript 类型。

CDN

有两种方式无需打包工具即可通过 CDN 使用 TRACIO。

边缘脚本（自动初始化）

边缘脚本会使用 k 查询参数中的公钥自动初始化。无需编写任何 JavaScript：

HTML

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

npm 打包版（IIFE 全局变量）

你也可以从 unpkg 或 jsDelivr 加载已发布的 npm 打包版。它会暴露一个 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()

返回一个 Promise<TracioResult>，包含访客 ID 和机器人检测结果。

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 并暴露符合各自习惯的原语（provider、插件、hook、composable 和 service）。各框架的代码片段请参见 SDK 概览。

性能考量

非阻塞：Tracio.init() 同步返回并在后台加载代理。它不会阻塞页面渲染。
单次请求：每次识别只发起一次请求。
超时：识别受 timeoutMs（默认 15000ms）限制，因此缓慢的网络绝不会让你的代码无限期挂起。

JavaScript SDK

TRACIO JavaScript SDK（@tracio/sdk）采集浏览器信号并将其发送到 TRACIO 云端，用于访客识别和机器人检测。它轻量、非阻塞，并兼容所有现代浏览器。

安装

bash

npm install @tracio/sdk

该软件包提供 ESM、CJS 和 IIFE 构建版本，并附带完整的 TypeScript 类型。

CDN

有两种方式无需打包工具即可通过 CDN 使用 TRACIO。

边缘脚本（自动初始化）

边缘脚本会使用 k 查询参数中的公钥自动初始化。无需编写任何 JavaScript：

HTML

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

npm 打包版（IIFE 全局变量）

你也可以从 unpkg 或 jsDelivr 加载已发布的 npm 打包版。它会暴露一个 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()

返回一个 Promise<TracioResult>，包含访客 ID 和机器人检测结果。

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 并暴露符合各自习惯的原语（provider、插件、hook、composable 和 service）。各框架的代码片段请参见 SDK 概览。

性能考量

非阻塞：Tracio.init() 同步返回并在后台加载代理。它不会阻塞页面渲染。
单次请求：每次识别只发起一次请求。
超时：识别受 timeoutMs（默认 15000ms）限制，因此缓慢的网络绝不会让你的代码无限期挂起。