SDK React

Il pacchetto @tracio/react incapsula il core @tracio/sdk ed espone primitive React idiomatiche: un provider che monta l'agente e hook che restituiscono l'ID visitatore e il risultato dell'identificazione, con stato di caricamento ed errore.

Installazione

npm install @tracio/react @tracio/sdk

react (18 o 19) è una peer dependency e si presume sia già installato nell'app.

Setup

Avvolga l'applicazione con <TracioProvider>. Monta l'agente TRACIO al primo render e chiama tracio.destroy() automaticamente quando il provider viene smontato.

import { TracioProvider } from "@tracio/react"

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

Prop del provider

Passi publicKey più le prop scalari piatte, oppure un oggetto config completo. Quando entrambi sono forniti, vince config.

Hook

useVisitorId()

Restituisce l'identificatore stabile del visitatore con stato di caricamento ed errore.

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

getId() recupera nuovamente l'ID visitatore in modo imperativo.

useTracioResult(opts?)

Restituisce il TracioResult completo (ID visitatore più rilevamento dei bot).

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

opts.immediate ha come default true. Passi { immediate: false } per rimandare il recupero fino a quando non chiama getData() autonomamente — utile dietro un gate di consenso:

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

function onConsent() {
  getData() // identifica solo dopo che l'utente ha dato il consenso
}

useTracio()

Escape hatch che restituisce l'istanza sottostante per usi avanzati.

const { tracio } = useTracio()

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

Prossimi passi

• Riferimento SDK JavaScript — l'API core @tracio/sdk su cui si basano gli hook
• Gestione degli errori — codici di errore e strategie di retry
• Panoramica degli SDK — tutti i pacchetti per framework a colpo d'occhio