Next.js blurs the line between client and server, which is exactly where device fingerprinting has to be careful. The rich signals that identify a device can only be gathered in the browser, but the decision you make from them must happen somewhere the browser cannot tamper with. Get that boundary right and fingerprinting slots cleanly into the App Router; get it wrong and you have a verdict an attacker can forge in the dev tools.
This guide walks through a correct Next.js integration: collecting signals in a client component, verifying server-side in a route handler or server action, and using edge middleware for cheap pre-filtering. It assumes the App Router, though the principles apply to the Pages Router too.
The client and server split that matters
The fundamental rule of any device fingerprinting integration is that the client identifies and the server decides. In Next.js this maps naturally onto the component model.
- Client components run in the browser and can access the APIs fingerprinting depends on, such as canvas, WebGL, and audio. This is where you load the agent and obtain a request ID.
- Server components and route handlers run on your server and never touch browser APIs. This is where you verify the result and act on it.
The mistake to avoid is returning a verdict to the browser and trusting it. Anything the client receives, the client can rewrite. The only thing your server should take from the client is the request ID, which it exchanges for the real event with GET /v1/events/{requestId} and its secret key. If you do not want the browser to see the result at all, turn on Sealed Results: the browser then gets only an encrypted blob that your server decrypts locally. Our React integration guide covers the component patterns in more depth, and the Node server-side verification article covers the backend exchange that Next.js route handlers wrap.
Collecting signals in a client component
Collection belongs in a 'use client' component because it needs browser APIs. Keep it small and let it hand the request ID up to your server.
Packages: Prynt’s npm packages are coming. Until then, use the script tag and the plain REST calls below; they work today.
A small loader module pulls the browser agent from the CDN once and reuses it. It only runs in the browser, never during server rendering:
// lib/prynt.ts: loads Prynt's browser agent from the CDN once (client side only).
declare global {
interface Window { Prynt: { load(config: Record<string, unknown>): Promise<PryntAgent> } }
}
export interface PryntAgent {
identify(opts?: { tag?: Record<string, unknown>; linkedId?: string }): Promise<{ requestId: string; visitorId: string }>;
}
let agent: Promise<PryntAgent> | undefined;
export function getPrynt(): Promise<PryntAgent> {
agent ??= new Promise<PryntAgent>((resolve, reject) => {
const s = document.createElement('script');
s.src = 'https://api.pryntid.com/cdn/prynt.umd.js';
s.async = true;
s.onload = () => resolve(window.Prynt.load({
apiKey: process.env.NEXT_PUBLIC_PRYNT_KEY, // pk_live_…
endpoint: 'https://api.pryntid.com',
extendedResult: true,
}));
s.onerror = () => { agent = undefined; reject(new Error('Prynt agent failed to load')); };
document.head.appendChild(s);
});
return agent;
}
'use client';
import { useEffect, useState } from 'react';
import { getPrynt } from '@/lib/prynt';
export function useVisitor() {
const [requestId, setRequestId] = useState<string | null>(null);
useEffect(() => {
getPrynt()
.then((p) => p.identify())
.then((r) => setRequestId(r.requestId))
.catch(() => { /* agent blocked: the server decides what a missing ID means */ });
}, []);
return requestId;
}
The loader above talks to api.pryntid.com directly. Serving the agent through a first-party path such as /_prynt is worth the extra step. Third-party scripts get stripped by ad-blockers and privacy extensions, which silently degrades your coverage. First-party agent serving explains why routing the agent through your own domain preserves signal quality, and Next.js rewrites make the proxy a few lines of config.
Verifying in a route handler
The request ID is meaningless until your server exchanges it for the actual device intelligence. In the App Router this is a route handler under app/api.
Prynt’s server API is plain HTTPS, so a small server-only helper does the exchange:
// lib/prynt-server.ts: Prynt's server API is plain HTTPS; no package to install.
const PRYNT_API = 'https://api.pryntid.com/v1';
async function pryntApi<T = any>(method: string, path: string, body?: unknown): Promise<T> {
const res = await fetch(PRYNT_API + path, {
method,
headers: {
Authorization: `Bearer ${process.env.PRYNT_SECRET_KEY}`, // server-only secret, sk_live_…
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
// 404 = unknown requestId, 401 = bad secret key
throw Object.assign(new Error(`Prynt ${method} ${path} failed: ${res.status}`), { status: res.status });
}
return res.json() as Promise<T>;
}
export const prynt = {
getEvent: (requestId: string) => pryntApi('GET', `/events/${encodeURIComponent(requestId)}`),
};
// app/api/verify/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { prynt } from '@/lib/prynt-server';
export async function POST(req: NextRequest) {
const { requestId } = await req.json();
const result = await prynt.getEvent(requestId);
const risky =
result.confidence.score > 0.9 &&
(result.smartSignals.bot?.result || result.smartSignals.residentialProxy?.result);
return NextResponse.json({
visitorId: result.visitorId,
action: risky ? 'step_up' : 'allow',
});
}
Two details make this correct. First, the secret key lives in a server-only environment variable and never reaches the bundle. Second, the browser gets back an action, not the raw signals, so it cannot learn exactly what tripped the decision or replay it. Wire this into a signup fraud or login protection flow and the verdict becomes something you can trust.
Edge middleware for cheap pre-filtering
Next.js middleware runs at the edge before the page renders, on every matched request. It cannot do full fingerprinting because there is no browser yet, but it is the perfect place for coarse, header-and-IP checks that reject the obvious junk before it consumes any application work.
// middleware.ts
import { NextResponse, NextRequest } from 'next/server';
export function middleware(req: NextRequest) {
const ip = req.headers.get('x-forwarded-for') ?? '';
const ua = req.headers.get('user-agent') ?? '';
if (isKnownBadAsn(ip) || isObviousBot(ua)) {
return new NextResponse('Forbidden', { status: 403 });
}
return NextResponse.next();
}
export const config = { matcher: ['/login', '/signup', '/api/:path*'] };
This mirrors the two-tier pattern from server-side versus client-side bot detection: filter cheaply at the edge, inspect deeply on the client, decide on the server. Middleware handles the first tier, the client component the second, and the route handler the third.
Putting the flow together
The end-to-end path in an App Router application:
- Middleware rejects obvious bot traffic at the edge.
- A client component loads the agent through a first-party rewrite and obtains a request ID.
- The client posts the request ID to a route handler or server action.
- The handler verifies it server-side with the secret key and returns an action.
- Your protected flow, such as signup or checkout, honors that action.
| Layer | Runs where | Job |
|---|---|---|
| Middleware | Edge | Reject obvious bots |
| Client component | Browser | Collect signals, get request ID |
| Route handler | Server | Verify, decide, return action |
Frequently asked questions
Where should I verify a fingerprint in Next.js?
Always verify server-side in a route handler or server action, never in the browser. The client obtains a request ID, and your server exchanges it for the verified event with its secret key so an attacker cannot forge the verdict.
Can I fingerprint in Next.js middleware?
Middleware runs before the page and is ideal for coarse edge checks using request headers and IP, but full device fingerprinting needs the browser, so the rich signals are collected client-side and verified in a route handler.
Does fingerprinting work with the App Router and server components?
Yes. Collect signals in a client component, send the request ID to a server action or route handler, and verify there. Server components cannot access browser APIs, so collection stays on the client boundary.
A clean Next.js integration respects the client-server boundary at every step: browser collects, edge pre-filters, server decides. Keep the secret key server-side, serve the agent first-party, and return actions rather than raw signals. See the SDKs page for other platforms, or try the signals live in the playground before you wire them in.
Try it free
Prynt is device intelligence with a free plan: 5,000 identifications a month, visitor IDs with confidence and bot detection — no credit card. Upgrade to Pro for VPN, proxy, tampering and behavioral signals.