React SDK

Пакет @tracio/react оборачивает базовый @tracio/sdk и предоставляет идиоматичные примитивы React: провайдер, монтирующий агента, и хуки, которые отдают вам идентификатор посетителя и результат идентификации вместе со статусами загрузки и ошибки.

Установка

npm install @tracio/react @tracio/sdk

react (18 или 19) является peer-зависимостью и предполагается уже установленным в вашем приложении.

Настройка

Оберните ваше приложение в <TracioProvider>. Он монтирует агента TRACIO при первом рендере и автоматически вызывает tracio.destroy(), когда провайдер размонтируется.

import { TracioProvider } from "@tracio/react"

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

Props провайдера

Передавайте либо publicKey вместе с плоскими скалярами, либо полный объект config. Если указано и то и другое, побеждает config.

Хуки

useVisitorId()

Возвращает стабильный идентификатор посетителя вместе со статусами загрузки и ошибки.

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

getId() императивно перезапрашивает идентификатор посетителя.

useTracioResult(opts?)

Возвращает полный TracioResult (идентификатор посетителя плюс обнаружение ботов).

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

opts.immediate по умолчанию равно true. Передайте { immediate: false }, чтобы отложить запрос до момента, когда вы сами вызовете getData() — полезно за барьером согласия (consent gate):

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

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

useTracio()

Запасной выход, возвращающий базовый экземпляр для продвинутого использования.

const { tracio } = useTracio()

Полный пример

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

Следующие шаги

• Справочник JavaScript SDK — базовый API @tracio/sdk, на котором строятся хуки
• Обработка ошибок — коды ошибок и стратегии повторных попыток
• Обзор SDK — каждый пакет для фреймворка с одного взгляда