Next.js Integration

Installation

npm install @fingerprintiq/js

yarn add @fingerprintiq/js

pnpm add @fingerprintiq/js

FingerprintIQ uses browser APIs (canvas, WebGL, audio context) and cannot run in Server Components. Any component that uses the SDK must be marked with 'use client'.

Client-Side Identification

Create a reusable hook in a client component:

tsx
// components/Fingerprint.tsx
'use client';

import { useEffect, useRef, useState } from 'react';
import FingerprintIQ from '@fingerprintiq/js';

export function useFingerprint() {
  const [visitorId, setVisitorId] = useState<string | null>(null);
  const [botProbability, setBotProbability] = useState<number | null>(null);
  const fiqRef = useRef<FingerprintIQ | null>(null);

  useEffect(() => {
    async function init() {
      if (!fiqRef.current) {
        fiqRef.current = new FingerprintIQ({
          apiKey: process.env.NEXT_PUBLIC_FIQ_API_KEY!,
        });
      }
      const result = await fiqRef.current.identify();
      setVisitorId(result.visitorId);
      setBotProbability(result.botProbability);
    }
    init().catch(console.error);
  }, []);

  return { visitorId, botProbability };
}

Server-Side Verification

After identifying on the client, send the visitorId to your API route for verification. This prevents spoofed visitor IDs from bypassing your trust logic.

typescript
// app/api/verify/route.ts
import { NextResponse } from 'next/server';

export async function POST(req: Request) {
  const { visitorId } = await req.json();

  const res = await fetch(
    `https://api.fingerprintiq.com/v1/demo/visits/${visitorId}`,
    {
      headers: {
        'X-API-Key': process.env.FIQ_SECRET_KEY!,
        'Content-Type': 'application/json',
      },
    }
  );

  const data = await res.json();

  const isLegitimate =
    data.totalVisits >= 1 &&
    data.visits[0]?.confidence >= 0.8 &&
    data.visits[0]?.botProbability < 0.3;

  return NextResponse.json({
    verified: isLegitimate,
    isReturning: data.totalVisits > 1,
    firstSeen: data.firstSeenAt,
    totalVisits: data.totalVisits,
  });
}

Environment Variables

env
# .env.local
NEXT_PUBLIC_FIQ_API_KEY=fiq_live_your_public_key
FIQ_SECRET_KEY=fiq_live_your_secret_key

Never expose your secret API key to the client. The NEXT_PUBLIC_ prefix makes variables available in the browser — only use it for your public key. The secret key must stay server-side only.

Full Integration Example

Putting it all together — identify on the client, verify on the server, gate a feature:

tsx
// app/checkout/page.tsx
'use client';

import { useEffect } from 'react';
import { useFingerprint } from '@/components/Fingerprint';

export default function CheckoutPage() {
  const { visitorId, botProbability } = useFingerprint();

  useEffect(() => {
    if (!visitorId) return;

    // Send to your server for verification
    fetch('/api/verify', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ visitorId }),
    })
      .then(res => res.json())
      .then(data => {
        if (!data.verified) {
          // Redirect or show challenge
          window.location.href = '/verify';
        }
      });
  }, [visitorId]);

  if (botProbability !== null && botProbability > 0.7) {
    return <div>Access denied. Suspicious activity detected.</div>;
  }

  return <CheckoutForm />;
}

Add FingerprintIQ identification to your root layout so the visitor ID is available by the time users reach protected pages — avoiding a waterfall of identify → verify → render.

typescript
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export async function middleware(request: NextRequest) {
  const visitorId = request.cookies.get('fiq_visitor_id')?.value;

  if (!visitorId) {
    // First visit — allow through, fingerprint will run client-side
    return NextResponse.next();
  }

  // Optional: verify visitorId against FingerprintIQ API
  // Be mindful of latency — this adds an extra API call to every request
  return NextResponse.next();
}

export const config = {
  matcher: ['/checkout/:path*', '/api/protected/:path*'],
};