快速开始

本指南将带你把 TRACIO 集成到你的应用中。你将安装客户端 SDK、使用公钥完成初始化，并读取第一个访客识别结果。

第 1 步：安装 SDK

使用你喜欢的包管理器安装 TRACIO SDK：

bash

npm install @tracio/sdk

或使用 pnpm：

bash

pnpm add @tracio/sdk

或使用 yarn：

bash

yarn add @tracio/sdk

免构建 CDN 代码片段

如果你不使用打包工具，只需把 edge 脚本标签放入页面即可。它会使用 k 查询参数中的公钥自动完成初始化：

HTML

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

第 2 步：初始化 SDK

导入 Tracio 并使用你的公钥调用 Tracio.init()。该调用会立即返回一个 TracioInstance —— 底层 agent 在后台加载。

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` 或 `eu` 以固定区域。
`endpoint`	`string`	自动	自定义 API 端点（用于第一方代理端点）。
`scriptUrl`	`string`	自动	agent 脚本的自定义 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 步：生命周期与错误

使用生命周期回调，在 agent 就绪或发生失败时做出响应，并使用 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()

有关错误码及重试辅助工具的完整列表，请参阅错误处理。

常见集成模式

登录保护

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()
}

后续步骤

工作原理 —— 了解信号采集与识别流程
JavaScript SDK 参考 —— 完整的 SDK API 文档
Webhooks —— 在你的服务器上实时接收识别事件
机器人检测 —— 深入了解自动化检测

快速开始

本指南将带你把 TRACIO 集成到你的应用中。你将安装客户端 SDK、使用公钥完成初始化，并读取第一个访客识别结果。

第 1 步：安装 SDK

使用你喜欢的包管理器安装 TRACIO SDK：

bash

npm install @tracio/sdk

或使用 pnpm：

bash

pnpm add @tracio/sdk

或使用 yarn：

bash

yarn add @tracio/sdk

免构建 CDN 代码片段

如果你不使用打包工具，只需把 edge 脚本标签放入页面即可。它会使用 k 查询参数中的公钥自动完成初始化：

HTML

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

第 2 步：初始化 SDK

导入 Tracio 并使用你的公钥调用 Tracio.init()。该调用会立即返回一个 TracioInstance —— 底层 agent 在后台加载。

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` 或 `eu` 以固定区域。
`endpoint`	`string`	自动	自定义 API 端点（用于第一方代理端点）。
`scriptUrl`	`string`	自动	agent 脚本的自定义 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 步：生命周期与错误

使用生命周期回调，在 agent 就绪或发生失败时做出响应，并使用 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()

有关错误码及重试辅助工具的完整列表，请参阅错误处理。

常见集成模式

登录保护

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()
}

后续步骤

工作原理 —— 了解信号采集与识别流程
JavaScript SDK 参考 —— 完整的 SDK API 文档
Webhooks —— 在你的服务器上实时接收识别事件
机器人检测 —— 深入了解自动化检测