React SDK

O pacote @tracio/react encapsula o núcleo @tracio/sdk e expõe primitivas idiomáticas do React: um provider que monta o agente e hooks que entregam a você o ID de visitante e o resultado de identificação com estado de carregamento e de erro.

Instalação

npm install @tracio/react @tracio/sdk

react (18 ou 19) é uma peer dependency e espera-se que já esteja instalado no seu app.

Configuração

Envolva sua aplicação com <TracioProvider>. Ele monta o agente TRACIO na primeira renderização e chama tracio.destroy() automaticamente quando o provider é desmontado.

import { TracioProvider } from "@tracio/react"

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

Props do provider

Passe publicKey mais os escalares planos, ou um objeto config completo. Quando ambos são fornecidos, config vence.

Hooks

useVisitorId()

Retorna o identificador estável de visitante com estado de carregamento e de erro.

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

getId() rebusca o ID de visitante de forma imperativa.

useTracioResult(opts?)

Retorna o TracioResult completo (ID de visitante mais detecção de bots).

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

opts.immediate tem true como padrão. Passe { immediate: false } para adiar a busca até que você mesmo chame getData() — útil atrás de um gate de consentimento:

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

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

useTracio()

Escape hatch que retorna a instância subjacente para uso avançado.

const { tracio } = useTracio()

Exemplo completo

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

Próximos passos

• JavaScript SDK Reference — a API central @tracio/sdk sobre a qual os hooks são construídos
• Error Handling — códigos de erro e estratégias de retry
• SDKs overview — cada pacote de framework em um relance