JavaScript SDK

TRACIO JavaScript SDK (@tracio/sdk) thu thập các tín hiệu từ trình duyệt và gửi chúng đến TRACIO cloud để định danh khách truy cập và phát hiện bot. Nó nhẹ, không chặn (non-blocking) và tương thích với mọi trình duyệt hiện đại.

Cài đặt

bash

npm install @tracio/sdk

Gói này cung cấp các bản build ESM, CJS và IIFE cùng với đầy đủ kiểu TypeScript.

CDN

Có hai cách để sử dụng TRACIO từ CDN mà không cần bundler.

Script edge (tự khởi tạo)

Script edge tự khởi tạo bằng public key trong tham số truy vấn k. Không cần viết JavaScript:

HTML

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

Gói npm (biến toàn cục IIFE)

Bạn cũng có thể tải gói npm đã phát hành từ unpkg hoặc jsDelivr. Nó cung cấp một biến toàn cục TracioSDK. Hãy ghim (pin) một phiên bản cụ thể:

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>

Khởi tạo

Tracio.init(config)

Khởi tạo SDK và trả về một TracioInstance một cách đồng bộ. Agent được tải ở chế độ nền; các phương thức của instance sẽ được giải quyết (resolve) ngay khi agent sẵn sàng.

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
}

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ầm định lưu trú dữ liệu tại Mỹ). Đặt tường minh để ghim `us` hoặc `eu`.
`endpoint`	`string`	tự động	Endpoint API tùy chỉnh (cho endpoint được proxy dưới dạng first-party).
`scriptUrl`	`string`	tự động	URL tùy chỉnh cho script agent (cho endpoint được proxy dưới dạng 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 được đính kèm 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 (timeout).

Gọi Tracio.init() nhiều hơn một lần với một public key khác sẽ ném ra lỗi multiple_keys.

Định danh

tracio.getVisitorId()

Trả về một Promise<string> được giải quyết thành định danh khách truy cập ổn định.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Trả về một Promise<TracioResult> chứa ID khách truy cập và kết quả phát hiện bot.

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[]
  }
}

Callback vòng đời

tracio.onReady(cb)

Được gọi khi agent đã tải xong và tạo ra kết quả.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Được gọi khi SDK gặp lỗi.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Hủy instance và giải phóng tài nguyên. Các lệnh gọi sau đó sẽ bị từ chối với lỗi destroyed.

TypeScript

tracio.destroy()

Xử lý lỗi

SDK ném ra các instance TracioError với một code có kiểu xác định. Sử dụng các hàm trợ giúp isTracioError và isRetryableError để phân nhánh:

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

Mã lỗi

Union TracioErrorCode bao gồm:

Mã	Mô tả
`blocked`	Yêu cầu đã bị chặn (ví dụ bởi một trình chặn quảng cáo).
`destroyed`	Instance đã bị hủy trước khi lệnh gọi hoàn tất.
`invalid_config`	Cấu hình không hợp lệ (ví dụ thiếu `publicKey`).
`load_failed`	Không thể tải script agent.
`multiple_keys`	`Tracio.init()` được gọi với một public key mâu thuẫn.
`network`	Một yêu cầu mạng đã thất bại.
`non_browser`	SDK được sử dụng bên ngoài môi trường trình duyệt.
`script_error`	Script agent đã ném ra lỗi trong thời gian chạy.
`server`	Máy chủ trả về một lỗi.
`timeout`	Yêu cầu đã vượt quá `timeoutMs`.

load_failed, blocked, script_error, network, timeout và server có thể thử lại; isRetryableError(error) trả về true cho chúng.

Tích hợp Framework

Với React, Vue, Angular và Svelte, hãy dùng các gói framework chuyên dụng thay vì tự đấu nối core SDK bằng tay:

Mỗi gói bao bọc @tracio/sdk và cung cấp các primitive theo phong cách của từng framework (provider, plugin, hook, composable và service). Xem tổng quan SDK để có các đoạn mã cho từng framework.

Cân nhắc về hiệu năng

Không chặn (non-blocking): Tracio.init() trả về đồng bộ và tải agent ở chế độ nền. Nó không chặn việc kết xuất (render) trang.
Một yêu cầu duy nhất: Mỗi lần định danh chỉ thực hiện một yêu cầu.
Timeout: Việc định danh bị giới hạn bởi timeoutMs (mặc định 15000ms), nên mạng chậm không bao giờ khiến mã của bạn treo vô thời hạn.

JavaScript SDK

Cài đặt

bash

npm install @tracio/sdk

Gói này cung cấp các bản build ESM, CJS và IIFE cùng với đầy đủ kiểu TypeScript.

CDN

Có hai cách để sử dụng TRACIO từ CDN mà không cần bundler.

Script edge (tự khởi tạo)

Script edge tự khởi tạo bằng public key trong tham số truy vấn k. Không cần viết JavaScript:

HTML

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

Gói npm (biến toàn cục IIFE)

Bạn cũng có thể tải gói npm đã phát hành từ unpkg hoặc jsDelivr. Nó cung cấp một biến toàn cục TracioSDK. Hãy ghim (pin) một phiên bản cụ thể:

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>

Khởi tạo

Tracio.init(config)

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
}

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ầm định lưu trú dữ liệu tại Mỹ). Đặt tường minh để ghim `us` hoặc `eu`.
`endpoint`	`string`	tự động	Endpoint API tùy chỉnh (cho endpoint được proxy dưới dạng first-party).
`scriptUrl`	`string`	tự động	URL tùy chỉnh cho script agent (cho endpoint được proxy dưới dạng 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 được đính kèm 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 (timeout).

Gọi Tracio.init() nhiều hơn một lần với một public key khác sẽ ném ra lỗi multiple_keys.

Định danh

tracio.getVisitorId()

Trả về một Promise<string> được giải quyết thành định danh khách truy cập ổn định.

TypeScript

const visitorId = await tracio.getVisitorId()
// "X7fh2Hg9LkMn3pQr"

tracio.getResult()

Trả về một Promise<TracioResult> chứa ID khách truy cập và kết quả phát hiện bot.

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[]
  }
}

Callback vòng đời

tracio.onReady(cb)

Được gọi khi agent đã tải xong và tạo ra kết quả.

TypeScript

tracio.onReady((result) => {
  console.log("ready:", result.visitorId)
})

tracio.onError(cb)

Được gọi khi SDK gặp lỗi.

TypeScript

tracio.onError((error) => {
  console.error("tracio error:", error.code, error.message)
})

tracio.destroy()

Hủy instance và giải phóng tài nguyên. Các lệnh gọi sau đó sẽ bị từ chối với lỗi destroyed.

TypeScript

tracio.destroy()

Xử lý lỗi

SDK ném ra các instance TracioError với một code có kiểu xác định. Sử dụng các hàm trợ giúp isTracioError và isRetryableError để phân nhánh:

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

Mã lỗi

Union TracioErrorCode bao gồm:

Mã	Mô tả
`blocked`	Yêu cầu đã bị chặn (ví dụ bởi một trình chặn quảng cáo).
`destroyed`	Instance đã bị hủy trước khi lệnh gọi hoàn tất.
`invalid_config`	Cấu hình không hợp lệ (ví dụ thiếu `publicKey`).
`load_failed`	Không thể tải script agent.
`multiple_keys`	`Tracio.init()` được gọi với một public key mâu thuẫn.
`network`	Một yêu cầu mạng đã thất bại.
`non_browser`	SDK được sử dụng bên ngoài môi trường trình duyệt.
`script_error`	Script agent đã ném ra lỗi trong thời gian chạy.
`server`	Máy chủ trả về một lỗi.
`timeout`	Yêu cầu đã vượt quá `timeoutMs`.

load_failed, blocked, script_error, network, timeout và server có thể thử lại; isRetryableError(error) trả về true cho chúng.

Tích hợp Framework

Với React, Vue, Angular và Svelte, hãy dùng các gói framework chuyên dụng thay vì tự đấu nối core SDK bằng tay:

Cân nhắc về hiệu năng

Không chặn (non-blocking): Tracio.init() trả về đồng bộ và tải agent ở chế độ nền. Nó không chặn việc kết xuất (render) trang.
Một yêu cầu duy nhất: Mỗi lần định danh chỉ thực hiện một yêu cầu.
Timeout: Việc định danh bị giới hạn bởi timeoutMs (mặc định 15000ms), nên mạng chậm không bao giờ khiến mã của bạn treo vô thời hạn.