React & Next.js

Framework SDK

Hooks and provider for device identification, bot detection, and threat assessment in React apps.

Install

terminal

npm install @lightningresearch/react @lightningresearch/sdk

LRDefenderProvider

Wrap your component tree once. The provider creates a singleton LightningResearch client and shares it with all hooks via context.

providers.tsx

'use client';

import { LRDefenderProvider } from '@lightningresearch/react';

export function AppProviders({ children }: { children: React.ReactNode }) {
  return (
    <LRDefenderProvider
      apiKey={process.env.NEXT_PUBLIC_LR_API_KEY!}
      region="auto"
      privacy={{ consentRequired: false }}
    >
      {children}
    </LRDefenderProvider>
  );
}

Hooks reference

Hook

Options

Return type

useDeviceId

tag?, linkedId?, immediate?

data: IdentifyResponse | null, isLoading, error, refetch

useBot

immediate?

data: BotDetectionResponse | null, isLoading, error, refetch

useThreat

immediate?, ip?

data: ThreatAssessmentResponse | null, isLoading, error, refetch

useConsent

—

granted: boolean, setConsent(v: boolean)

useBehavioralTracking

—

start(), stop(), isTracking: boolean

useDeviceId

Identifies the current browser and returns deviceId, confidence, risk level, and visit metadata. Pass immediate: true to run on mount.

DeviceBadge.tsx

import { useDeviceId } from '@lightningresearch/react';

function DeviceBadge() {
  const { data, isLoading, error, refetch } = useDeviceId({
    immediate: true,
    tag: 'checkout',
    linkedId: 'user-42',
  });

  if (isLoading) return <span>Identifying…</span>;
  if (error) return <span>Error: {error.message}</span>;

  return (
    <span>
      {data?.deviceId} ({Math.round((data?.confidence ?? 0) * 100)}%)
    </span>
  );
}

useBot

BotGate.tsx

import { useBot } from '@lightningresearch/react';

function BotGate() {
  const { data, isLoading, refetch } = useBot({ immediate: true });

  if (isLoading) return null;
  if (data?.isBot) return <p>Automated traffic detected (score: {data.botScore})</p>;
  return <CheckoutForm />;
}

useThreat

ThreatBanner.tsx

import { useThreat } from '@lightningresearch/react';

function ThreatBanner() {
  const { data } = useThreat({ immediate: true, ip: '203.0.113.42' });

  if (data?.isVpn || data?.isProxy) {
    return <p>Elevated risk — VPN or proxy detected ({data.threatScore})</p>;
  }
  return null;
}

useConsent

ConsentBanner.tsx

import { useConsent } from '@lightningresearch/react';

function ConsentBanner() {
  const { granted, setConsent } = useConsent();

  if (granted) return null;
  return (
    <button onClick={() => setConsent(true)}>
      Accept analytics & device identification
    </button>
  );
}

useBehavioralTracking

Start and stop mouse, keyboard, scroll, and touch collection. Behavioral data improves bot detection when passed to useBot.

FraudForm.tsx

import { useBehavioralTracking } from '@lightningresearch/react';

function FraudForm() {
  const { start, stop, isTracking } = useBehavioralTracking();

  return (
    <form
      onFocus={start}
      onBlur={stop}
    >
      {isTracking && <span className="sr-only">Behavioral tracking active</span>}
      {/* form fields */}
    </form>
  );
}

Next.js App Router & SSR

The provider and all hooks ship with 'use client' — import them only in Client Components.
Hooks guard against SSR: API calls run only when typeof window !== 'undefined'.
Do not call identify() in Server Components or getServerSideProps — fingerprinting requires a browser runtime.
For server-side verification, mint collector sessions or call the Server API from Route Handlers.

app-router.tsx

'use client';

// All @lightningresearch/react hooks require a client component.
// Wrap your app in LRDefenderProvider inside a client boundary:

// app/providers.tsx
'use client';
import { LRDefenderProvider } from '@lightningresearch/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <LRDefenderProvider apiKey={process.env.NEXT_PUBLIC_LR_API_KEY!}>
      {children}
    </LRDefenderProvider>
  );
}

// app/layout.tsx (Server Component — no 'use client')
import { Providers } from './providers';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}