React SDK

Gói @tracio/react bao bọc lõi @tracio/sdk và cung cấp các primitive React đúng phong cách: một provider để mount agent, cùng các hook trả về cho bạn visitor ID và kết quả nhận diện kèm trạng thái loading và lỗi.

Cài đặt

npm install @tracio/react @tracio/sdk

react (18 hoặc 19) là một peer dependency và được giả định là đã được cài đặt sẵn trong ứng dụng của bạn.

Thiết lập

Bao bọc ứng dụng của bạn bằng <TracioProvider>. Nó mount agent TRACIO ở lần render đầu tiên và tự động gọi tracio.destroy() khi provider bị unmount.

import { TracioProvider } from "@tracio/react"

function Root() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <App />
    </TracioProvider>
  )
}

Props của Provider

Truyền vào hoặc publicKey cùng các scalar phẳng, hoặc một đối tượng config hoàn chỉnh. Khi cả hai được cung cấp, config sẽ thắng.

Hooks

useVisitorId()

Trả về định danh visitor ổn định kèm trạng thái loading và lỗi.

const { data, isLoading, error, isFetched, getId } = useVisitorId()
// data: string | undefined — the visitorId

getId() lấy lại visitor ID một cách chủ động.

useTracioResult(opts?)

Trả về TracioResult đầy đủ (visitor ID cùng phát hiện bot).

const { data, isLoading, error, isFetched, getData } = useTracioResult()
// data: TracioResult | undefined

opts.immediate mặc định là true. Truyền { immediate: false } để hoãn việc lấy dữ liệu cho đến khi bạn tự gọi getData() — hữu ích khi đặt sau một cổng đồng ý (consent gate):

const { data, getData } = useTracioResult({ immediate: false })

function onConsent() {
  getData() // identify only after the user opts in
}

useTracio()

Lối thoát (escape hatch) trả về instance nền tảng bên dưới cho các trường hợp sử dụng nâng cao.

const { tracio } = useTracio()

Ví dụ đầy đủ

import { TracioProvider, useVisitorId } from "@tracio/react"
function App() {
  return (
    <TracioProvider publicKey={process.env.NEXT_PUBLIC_TRACIO_KEY!}>
      <Page />
    </TracioProvider>
  )
}
function Page() {
  const { data: visitorId, isLoading, error } = useVisitorId()
  if (isLoading) return <span>Loading…</span>
  if (error) return <span>Error: {error.message}</span>
  return <span>Visitor: {visitorId}</span>
}

Các bước tiếp theo

• Tài liệu tham khảo JavaScript SDK — API lõi @tracio/sdk mà các hook được xây dựng trên đó
• Xử lý lỗi — mã lỗi và chiến lược retry
• Tổng quan các SDK — mọi gói framework trong một cái nhìn tổng thể