@tracetail/react

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

Install

npm install @tracetail/react

Quick start

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

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. 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 regenerate() to try again. 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 and a secret server key (tts_…, created in Settings → API keys and kept on your server):

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 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. An agent gets the API keys through a setup link: 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.

License

MIT