Bắt đầu nhanh

Hướng dẫn này sẽ dẫn bạn qua việc tích hợp TRACIO vào ứng dụng của bạn. Bạn sẽ cài đặt client SDK, khởi tạo nó với public key của bạn và đọc kết quả nhận dạng khách truy cập đầu tiên.

Bước 1: Cài đặt SDK

Cài đặt TRACIO SDK bằng trình quản lý gói ưa thích của bạn:

bash

npm install @tracio/sdk

Hoặc với pnpm:

bash

pnpm add @tracio/sdk

Hoặc với yarn:

bash

yarn add @tracio/sdk

Đoạn mã CDN không cần build

Nếu bạn không dùng bundler, hãy thêm thẻ edge script vào trang của bạn. Nó tự động khởi tạo với public key trong tham số truy vấn k:

HTML

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

Bước 2: Khởi tạo SDK

Import Tracio và gọi Tracio.init() với public key của bạn. Hàm này trả về một TracioInstance ngay lập tức — agent bên dưới được tải trong nền.

TypeScript

import { Tracio } from "@tracio/sdk"

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

Public key của bạn an toàn để đưa vào code phía client. Bạn có thể tìm thấy nó trong dashboard ở mục API Keys.

Tùy chọn cấu hình

Tracio.init() nhận vào một đối tượng TracioConfig:

Tùy chọn	Kiểu	Mặc định	Mô tả
`publicKey`	`string`	bắt buộc	Public key của bạn. Sao chép nó từ dashboard của bạn.
`region`	`"us" \| "eu"`	không có	Vùng dữ liệu tùy chọn. Khi không đặt, SDK dùng endpoint chung `https://edge.tracio.ai` (không ngụ ý lưu trú dữ liệu tại US). Đặt rõ ràng để ghim `us` hoặc `eu`.
`endpoint`	`string`	tự động	API endpoint tùy chỉnh (cho endpoint được proxy first-party).
`scriptUrl`	`string`	tự động	URL tùy chỉnh cho script của agent (cho endpoint được proxy first-party).
`linkedId`	`string`	không có	Định danh liên kết khách truy cập này với một thực thể trong hệ thống của bạn.
`tag`	`string`	không có	Nhãn tự do gắn vào yêu cầu để lọc về sau.
`debug`	`boolean`	`false`	Ghi log chẩn đoán chi tiết ra console.
`timeoutMs`	`number`	`15000`	Thời gian chờ kết quả trước khi hết thời gian.

Bước 3: Lấy Visitor ID

Gọi tracio.getVisitorId() để nhận một định danh khách truy cập ổn định. Đây là một thao tác bất đồng bộ.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Bước 4: Đọc kết quả đầy đủ

Gọi tracio.getResult() để nhận kết quả nhận dạng đầy đủ, bao gồm cả phát hiện bot.

TypeScript

const result = await tracio.getResult()

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

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

Kết quả có dạng:

TypeScript

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

Bước 5: Vòng đời và lỗi

Dùng các callback vòng đời để phản ứng khi agent sẵn sàng hoặc khi có lỗi, và destroy() để hủy instance:

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

Xem Xử lý lỗi để biết danh sách đầy đủ các mã lỗi và các hàm trợ giúp thử lại.

Các mẫu tích hợp phổ biến

Bảo vệ đăng nhập

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

Ngăn chặn gian lận thanh toán

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

Các bước tiếp theo

Cách hoạt động — Hiểu về pipeline thu thập tín hiệu và nhận dạng
Tài liệu tham khảo JavaScript SDK — Tài liệu API đầy đủ của SDK
Webhooks — Nhận sự kiện nhận dạng trên server của bạn theo thời gian thực
Phát hiện bot — Tìm hiểu sâu về phát hiện tự động hóa

Bắt đầu nhanh

Bước 1: Cài đặt SDK

Cài đặt TRACIO SDK bằng trình quản lý gói ưa thích của bạn:

bash

npm install @tracio/sdk

Hoặc với pnpm:

bash

pnpm add @tracio/sdk

Hoặc với yarn:

bash

yarn add @tracio/sdk

Đoạn mã CDN không cần build

Nếu bạn không dùng bundler, hãy thêm thẻ edge script vào trang của bạn. Nó tự động khởi tạo với public key trong tham số truy vấn k:

HTML

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

Bước 2: Khởi tạo SDK

Import Tracio và gọi Tracio.init() với public key của bạn. Hàm này trả về một TracioInstance ngay lập tức — agent bên dưới được tải trong nền.

TypeScript

import { Tracio } from "@tracio/sdk"

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

Public key của bạn an toàn để đưa vào code phía client. Bạn có thể tìm thấy nó trong dashboard ở mục API Keys.

Tùy chọn cấu hình

Tracio.init() nhận vào một đối tượng TracioConfig:

Tùy chọn	Kiểu	Mặc định	Mô tả
`publicKey`	`string`	bắt buộc	Public key của bạn. Sao chép nó từ dashboard của bạn.
`region`	`"us" \| "eu"`	không có	Vùng dữ liệu tùy chọn. Khi không đặt, SDK dùng endpoint chung `https://edge.tracio.ai` (không ngụ ý lưu trú dữ liệu tại US). Đặt rõ ràng để ghim `us` hoặc `eu`.
`endpoint`	`string`	tự động	API endpoint tùy chỉnh (cho endpoint được proxy first-party).
`scriptUrl`	`string`	tự động	URL tùy chỉnh cho script của agent (cho endpoint được proxy first-party).
`linkedId`	`string`	không có	Định danh liên kết khách truy cập này với một thực thể trong hệ thống của bạn.
`tag`	`string`	không có	Nhãn tự do gắn vào yêu cầu để lọc về sau.
`debug`	`boolean`	`false`	Ghi log chẩn đoán chi tiết ra console.
`timeoutMs`	`number`	`15000`	Thời gian chờ kết quả trước khi hết thời gian.

Bước 3: Lấy Visitor ID

Gọi tracio.getVisitorId() để nhận một định danh khách truy cập ổn định. Đây là một thao tác bất đồng bộ.

TypeScript

const visitorId = await tracio.getVisitorId()

console.log(visitorId) // "X7fh2Hg9LkMn3pQr"

Bước 4: Đọc kết quả đầy đủ

Gọi tracio.getResult() để nhận kết quả nhận dạng đầy đủ, bao gồm cả phát hiện bot.

TypeScript

const result = await tracio.getResult()

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

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

Kết quả có dạng:

TypeScript

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

Bước 5: Vòng đời và lỗi

Dùng các callback vòng đời để phản ứng khi agent sẵn sàng hoặc khi có lỗi, và destroy() để hủy instance:

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

Xem Xử lý lỗi để biết danh sách đầy đủ các mã lỗi và các hàm trợ giúp thử lại.

Các mẫu tích hợp phổ biến

Bảo vệ đăng nhập

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

Ngăn chặn gian lận thanh toán

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

Các bước tiếp theo

Cách hoạt động — Hiểu về pipeline thu thập tín hiệu và nhận dạng
Tài liệu tham khảo JavaScript SDK — Tài liệu API đầy đủ của SDK
Webhooks — Nhận sự kiện nhận dạng trên server của bạn theo thời gian thực
Phát hiện bot — Tìm hiểu sâu về phát hiện tự động hóa