快速开始

本指南将带你把 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 查询参数中的公钥自动完成初始化。

选择脚本的加载来源。某些网络和浏览器扩展会拦截发往第三方分析域名的请求：企业过滤器、DNS 层面的拦截器、区域性限制、隐私扩展。从您自己的子域分发时，该脚本是您站点上的第一方请求，因而在这些环境中仍能正常工作——参见自定义域名：

HTML

<script src="https://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>

或者从共享的 edge 域名加载，这是最快的上手方式：

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` 时将被忽略。
`endpoint`	`string`	自动	您自己子域的 origin，例如 `https://metrics.yoursite.com`。脚本与信号都从它分发。参见自定义域名。
`scriptUrl`	`string`	自动	agent 脚本的完整 URL。它会替换整个 URL，包括公钥在内——若要使用自定义域名，请改用 `endpoint`。
`linkedId`	`string`	无	将此访客与你的系统中某个实体关联的标识符。参见账户关联。
`tag`	`string`	无	附加到请求上的自由格式标签，便于后续筛选。
`debug`	`boolean`	`false`	向控制台输出详细的诊断日志。
`timeoutMs`	`number`	`15000`	在超时之前等待结果的时长。

第 3 步：获取访客 ID

调用 tracio.getVisitorId() 以获取一个稳定的访客标识符。这是一个异步操作。

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

第 4 步：读取完整结果

调用 tracio.getResult() 以获取包含机器人检测在内的完整识别结果。

TypeScript

const result = await tracio.getResult()

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

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

结果的结构如下：

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  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 —— 在你的服务器上实时接收识别事件
Data API —— 从你的后端读取访客、会话与活动速率
机器人检测 —— 深入了解自动化检测

快速开始

本指南将带你把 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://metrics.yoursite.com/s.js?k=PUBLIC_KEY" async></script>

或者从共享的 edge 域名加载，这是最快的上手方式：

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` 时将被忽略。
`endpoint`	`string`	自动	您自己子域的 origin，例如 `https://metrics.yoursite.com`。脚本与信号都从它分发。参见自定义域名。
`scriptUrl`	`string`	自动	agent 脚本的完整 URL。它会替换整个 URL，包括公钥在内——若要使用自定义域名，请改用 `endpoint`。
`linkedId`	`string`	无	将此访客与你的系统中某个实体关联的标识符。参见账户关联。
`tag`	`string`	无	附加到请求上的自由格式标签，便于后续筛选。
`debug`	`boolean`	`false`	向控制台输出详细的诊断日志。
`timeoutMs`	`number`	`15000`	在超时之前等待结果的时长。

第 3 步：获取访客 ID

调用 tracio.getVisitorId() 以获取一个稳定的访客标识符。这是一个异步操作。

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

第 4 步：读取完整结果

调用 tracio.getResult() 以获取包含机器人检测在内的完整识别结果。

TypeScript

const result = await tracio.getResult()

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

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

结果的结构如下：

TypeScript

{
  visitorId: "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  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 —— 在你的服务器上实时接收识别事件
Data API —— 从你的后端读取访客、会话与活动速率
机器人检测 —— 深入了解自动化检测