skills/fingerprint-nextjs/SKILL.md

---
name: fingerprint-nextjs
description: Add Fingerprint to a fullstack Next.js (App Router) app — identify visitors in the browser with the React SDK and verify the event_id server-side with the node SDK in a Route Handler or Server Action.
---

# Fingerprint — Next.js

Integrate Fingerprint into a Next.js (App Router) app. Next.js does both halves in one codebase:
the **client identifies** the visitor (producing a single-use `event_id`) and the **server**
fetches that event from the Server API to read the verified identification and Smart Signals. The
browser never holds the secret key and never makes trust decisions — the server does, using the
checks below.

> Docs: React SDK https://docs.fingerprint.com/docs/react · Node Server SDK https://docs.fingerprint.com/reference/node-server-sdk · event schema: OpenAPI (https://github.com/fingerprintjs/fingerprint-pro-server-api-openapi) or the Fingerprint MCP event-schema resource.

## Packages
- `@fingerprint/react` — browser identification (client components). Install the latest version.
- `@fingerprint/node-sdk` — Server API verification (Route Handlers / Server Actions). Install the latest version.

## Env vars
Next.js only exposes env vars prefixed with `NEXT_PUBLIC_` to the browser bundle. Everything else
stays server-only.

- `NEXT_PUBLIC_FINGERPRINT_PUBLIC_API_KEY` — public key, shipped to the browser (safe).
- `NEXT_PUBLIC_FINGERPRINT_REGION` — workspace region for the client (`us` | `eu` | `ap`), shipped
  to the browser.
- `FINGERPRINT_SECRET_API_KEY` — secret key. **Server-only**; the missing `NEXT_PUBLIC_` prefix
  keeps it out of the client bundle. Never reference it from a client component.
- `FINGERPRINT_REGION` — workspace region for the server (`us` | `eu` | `ap`).

> Read public values via `process.env.NEXT_PUBLIC_*`; they are inlined into client code. Read the
> secret only inside server code (Route Handlers, Server Actions, server components). If you ever
> see `FINGERPRINT_SECRET_API_KEY` referenced from a `'use client'` file, that's a leak.

## Steps

### Client — identify
1. **Install** `@fingerprint/react`.

2. **Wrap the app in `FingerprintProvider`.** The provider is a client component, so put it in a
   small `'use client'` wrapper and render that wrapper inside `app/layout.tsx` around `{children}`.
   Pass the public key and region from the `NEXT_PUBLIC_` vars. See `snippets/provider.tsx` and
   `snippets/layout.tsx`.

3. **Identify on sensitive actions, not on every render.** In a client component, use
   `useVisitorData({ immediate: false })` and call `getData()` at the moment of a security-relevant
   action (login, signup, checkout, password reset). See `snippets/identify-on-action.tsx`.

4. **Send the `event_id` to the server** with the action request. `getData()` returns
   `{ visitor_id, event_id }`; send the **`event_id`** (single-use, server-verifiable). Do not trust
   the client `visitor_id` — the server re-derives it from the Server API.

### Server — verify
5. **Install** `@fingerprint/node-sdk`.

6. **Create one client** with the secret key and region (`Region.Global` | `Region.EU` |
   `Region.AP`, mapped from `FINGERPRINT_REGION`). Next.js loads `.env.local` automatically, so no
   `dotenv` is needed. See `snippets/fingerprint-server.ts`.

7. **Verify the `event_id`** before running the sensitive handler: call `client.getEvent(eventId)`
   and apply the checks below. Use it from either a Route Handler (`app/api/.../route.ts`) or a
   Server Action (`'use server'`). See `snippets/route-handler.ts` and `snippets/server-action.ts`.

## Verification checks (do all of them)
- **Found:** `event.identification.visitor_id` exists.
- **Replay / freshness:** reject if `event.replayed === true`, or if `event.timestamp` is older than
  your window (e.g. 2 minutes) — prevents reuse of an old `event_id`.
- **Confidence:** require `event.identification.confidence.score >= 0.9` for the action.
- **Smart signals** (fail-closed for high-risk actions): `event.bot !== "not_detected"`,
  `event.vpn`, `event.proxy`, `event.tampering`.
- **Identity match:** bind `visitor_id` ↔ user on first trusted use; re-check on later actions.

## v4 event shape (flat — per the Server API event schema)
`getEvent` returns the event object directly:
- `event.identification.visitor_id` — the trusted visitor id
- `event.identification.confidence.score` — 0..1 (probability of a false-positive identification)
- `event.timestamp` — Unix ms of the event
- `event.replayed` — `true` if the payload was replayed
- `event.bot` — `"bad" | "good" | "not_detected"`
- `event.vpn`, `event.proxy`, `event.tampering`, `event.incognito` — booleans
- `event.suspect_score` — weighted Smart-Signals score (integer)
- `event.velocity` (object), `event.ip_blocklist` (object: `attack_source`, `email_spam`,
  `tor_node`) — for abuse / ATO logic

## Best practices
- One `FingerprintProvider` at the app root; don't re-instantiate per component.
- Region must match the workspace region on **both** sides (`us` | `eu` | `ap`).
- Don't block the UI on identification; handle the hook's `isLoading`/error states.
- Verify server-side on **every** sensitive action; treat the client result as a hint only.
- Fail closed on lookup errors for high-risk flows.
- Each `event_id` is single-use per action — don't cache a pass/fail across requests.
- Keep the secret key out of logs and out of any `NEXT_PUBLIC_` var or client component.