# @tracetail/react

React hooks for TraceTail browser fingerprinting, with 99.6% accuracy: a stable visitor ID for every browser, without cookies or storage.

## Install

```bash
npm install @tracetail/react
```

## Quick start

```tsx
import { useTraceTail } from '@tracetail/react';

export function CheckoutForm() {
  const { fingerprint } = useTraceTail({ apiKey: 'YOUR_API_KEY', endpoint: 'https://tracetail.io/api' });

  return (
    <form method="post" action="/checkout">
      <input type="hidden" name="visitorId" value={fingerprint?.visitorId ?? ''} />
      {/* ... */}
    </form>
  );
}
```

Create a free API key at [tracetail.io/auth](https://tracetail.io/auth). Without an API key the hooks run keyless: the visitor ID is computed in the browser and nothing is sent anywhere.

## Configure once with a provider

```tsx
import { TraceTailProvider, useTraceTail } from '@tracetail/react';

root.render(
  <TraceTailProvider apiKey="YOUR_API_KEY" endpoint="https://tracetail.io/api">
    <App />
  </TraceTailProvider>,
);

function VisitorBadge() {
  const { fingerprint, loading } = useTraceTail();
  return <span>{loading ? 'Identifying…' : fingerprint?.visitorId}</span>;
}
```

When a provider prop changes (for example the API key), the hooks below it switch to a client with the new options and identify again.

## useTraceTail(options?)

| Option | Description |
| --- | --- |
| `apiKey`, `endpoint`, `timeout`, `debug` | Client options, as in [@tracetail/js](https://tracetail.io/docs). Omit them to use the nearest `TraceTailProvider`. |
| `verbose` | Include the collected signals in `fingerprint.components`. |
| `detailed` | Also return `riskAssessment` and `botDetection` (needs an API key). |
| `immediate` | Identify when the component mounts. Default: `true`. |

It returns:

| Field | Description |
| --- | --- |
| `fingerprint` | The result (`visitorId`, `confidence`, `processingTime`, `requestId`, `isBot` and so on), or `null` until identification completes. If the API call failed, `fingerprint.error` holds `{ status, code, message }` and `visitorId` is still set. |
| `loading` | `true` while identifying. |
| `error` | Set when identification itself failed, for example when called without a DOM. |
| `generate()` | Identify, reusing the page's cached result when there is one. |
| `regenerate()` | Identify again, bypassing the cache. |

Components using the same options share one client and its result, so a page identifies once. React StrictMode's double mount also makes a single request. The hooks never retry on their own; call `generate()` to retry a failed registration with its existing request token. `regenerate()` starts a new identification and can count as another request. Identification runs in an effect, so nothing runs during server-side rendering.

## Other hooks

- `useVisitorId(options?)` returns `{ visitorId, loading, error, regenerate }`.
- `useComplianceContext()` returns browser hints (Global Privacy Control, Do Not Track and the inferred region) for deciding whether to ask for consent before identifying. You are responsible for any consent your visitors' jurisdiction requires.

The package also re-exports `TraceTail`, `getComplianceContext` and the types from `@tracetail/js`.

## Verify on your server

The visitor ID comes from the browser, so your backend can't tell a real one from one a script made up. Before you trust it for a sign-up, login or payment, send `fingerprint.requestId` along and look it up with the [Server API](https://tracetail.io/docs#server-api) and a secret server key (`tts_…`, created in Settings → API keys and kept on your server):

```bash
curl https://tracetail.io/api/v1/identifications/$REQUEST_ID \
  -H "Authorization: Bearer $TRACETAIL_SERVER_KEY"
```

Check that the returned `visitorId` is the one your page sent. The [docs](https://tracetail.io/docs#server-api) have the full response and Node.js and Python examples.

## AI coding agents

Claude Code, Codex, Cursor and other agents can add TraceTail on their own. Connect the MCP server at `https://tracetail.io/mcp` (no account or key needed; in Claude Code, `claude mcp add --transport http tracetail https://tracetail.io/mcp`), install the skill with `npx skills add https://tracetail.io`, or point the agent at [llms.txt](https://tracetail.io/llms.txt). An agent gets the API keys through a [setup link](https://tracetail.io/docs#ai-agents-setup-links): it hands you one link, where you sign in with an emailed code and add a card or continue free, and receives a key for each site.

## Pricing

Every account includes 1,000 identification requests a month, with no card required. Beyond that it costs $0.10 per 1,000 requests. See [pricing](https://tracetail.io/pricing).

## License

MIT