skills/fingerprint-react/SKILL.md

---
name: fingerprint-react
description: Integrate Fingerprint device identification into a React (or Preact) app — initialize the agent and get the visitor's visitor_id and event_id.
---

# Fingerprint — React

Integrate Fingerprint into a React app to identify visitors: initialize the agent once at startup,
then ask it for the visitor's `visitor_id` and a single-use `event_id` wherever you need it (on
load, or on an action like login or checkout).

> Docs: https://docs.fingerprint.com/docs/react · JS Agent v4: https://docs.fingerprint.com/reference/js-agent-v4

## Package
`@fingerprint/react` — install the latest version. (Preact uses the same package. For plain HTML
or an unsupported framework, use `fingerprint-javascript` and `@fingerprint/agent` instead.)

## Env var
- `FINGERPRINT_PUBLIC_API_KEY` — the public key, safe to ship to the browser.

> Bundlers only expose prefixed vars to client code — map the key to the bundler's convention:
> - Vite: `VITE_FINGERPRINT_PUBLIC_API_KEY` → `import.meta.env.VITE_...`
> - Create React App: `REACT_APP_FINGERPRINT_PUBLIC_API_KEY` → `process.env.REACT_APP_...`
> Never expose `FINGERPRINT_SECRET_API_KEY` to the frontend.

## Steps

1. **Install** `@fingerprint/react`. On pnpm, the package's `postinstall` may be blocked with
   `ERR_PNPM_IGNORED_BUILDS` — run `pnpm approve-builds`, approve `@fingerprint/react`, then
   install again. Keep pnpm's build-script protection on.

2. **Initialize once at the app root.** Wrap the app in `FingerprintProvider`, passing the public
   key and region (`us` | `eu` | `ap`, matching the workspace). Client-side only. See
   `snippets/provider.jsx`.

3. **Get the identification where you need it.** Use `useVisitorData`. For identify-on-demand pass
   `{ immediate: false }` and call `getData()` on the action you care about; it returns
   `{ visitor_id, event_id, ... }`. See `snippets/use-visitor-data.jsx`.

4. **Verify it works.** Disable your ad blocker, run the dev server, trigger the call, and confirm
   a `visitor_id` is logged in the browser console (or that the event appears on the dashboard
   Events page).

## Notes
- Region must match the workspace (`us` | `eu` | `ap`).
- Initialize once at the root; don't re-instantiate per component. Don't block the UI on
  identification — handle the hook's `isLoading` / error states.
- **Production:** protect the agent from ad blockers with a custom subdomain or proxy —
  https://docs.fingerprint.com/docs/protecting-the-javascript-agent-from-adblockers.
- Don't use legacy `@fingerprintjs/fingerprintjs-pro`, `FingerprintJS.load()`, or `scriptUrlPattern`.