@keverdjs/fraud-sdk-react

React SDK for Keverd fraud detection and device fingerprinting. This SDK provides real-time risk assessment by analyzing device characteristics, behavioral biometrics, and session patterns.

Installation

Install the package via npm or yarn:

npm install @keverdjs/fraud-sdk-react

or

yarn add @keverdjs/fraud-sdk-react

Quick Start

1. Wrap your application with KeverdProvider

In your _app.tsx (Next.js) or root component:

import { KeverdProvider } from '@keverdjs/fraud-sdk-react';

function MyApp({ Component, pageProps }) {
  return (
    <KeverdProvider
      loadOptions={{
        apiKey: 'your-api-key-here',
      }}
    >
      <Component {...pageProps} />
    </KeverdProvider>
  );
}

export default MyApp;

2. Use the hook in your components

import { useKeverdVisitorData } from '@keverdjs/fraud-sdk-react';

export default function Home() {
  const { isLoading, error, data, getData } = useKeverdVisitorData({
    immediate: true, // Automatically fetch on mount
    extendedResult: true,
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <h1>Risk Score: {data?.riskScore}%</h1>
      <p>Action: {data?.action}</p>
      <p>Reasons: {data?.reasons.join(', ')}</p>
      <button onClick={() => getData()}>Refresh Data</button>
    </div>
  );
}

API Reference

KeverdProvider

The provider component that initializes the SDK and makes it available to child components.

Props:

interface KeverdProviderProps {
  loadOptions: KeverdLoadOptions;
  children: React.ReactNode;
}

KeverdLoadOptions:

interface KeverdLoadOptions {
  apiKey: string;              // Required: Your Keverd API key
  endpoint?: string;           // Optional: Custom API endpoint (default: https://app.keverd.com)
  debug?: boolean;             // Optional: Enable debug logging (default: false)
}

useKeverdVisitorData

Hook to access visitor data and risk assessment results.

Usage:

const { 
  data,           // KeverdVisitorData | null
  isLoading,      // boolean
  error,          // KeverdError | null
  getData         // () => Promise<void>
} = useKeverdVisitorData(options?);

Options:

interface KeverdVisitorDataHookOptions {
  extendedResult?: boolean;    // Include extended device/session info (default: false)
  immediate?: boolean;          // Automatically fetch data on mount (default: false)
  ignoreCache?: boolean;        // Ignore cached data (default: false)
}

Return Value:

interface KeverdVisitorDataResult {
  isLoading: boolean;          // Loading state
  error: KeverdError | null;   // Error if any
  data: KeverdVisitorData | null; // Visitor data
  getData: (options?: KeverdVisitorDataOptions) => Promise<KeverdVisitorData>;
}

interface KeverdVisitorData {
  visitorId: string;
  riskScore: number;           // 0-100
  score: number;               // 0.0-1.0
  action: 'allow' | 'soft_challenge' | 'hard_challenge' | 'block';
  reasons: string[];           // Array of risk reasons
  sessionId: string;           // Session identifier
  requestId: string;           // Request identifier
  simSwapEngine?: KeverdSimSwapEngine; // SIM swap detection (null for web)
  confidence?: number;         // Confidence score (if available)
}

useKeverdContext

Hook to access the underlying SDK instance (for advanced usage).

import { useKeverdContext } from '@keverdjs/fraud-sdk-react';

const sdk = useKeverdContext();
// Use sdk methods directly

Configuration

Custom Endpoint

If you're using a custom backend endpoint:

<KeverdProvider
  loadOptions={{
    apiKey: 'your-api-key',
    endpoint: 'https://api.yourdomain.com/v1/fingerprint/score',
  }}
>
  {children}
</KeverdProvider>

Debug Mode

Enable debug logging for development:

<KeverdProvider
  loadOptions={{
    apiKey: 'your-api-key',
    debug: true,
  }}
>
  {children}
</KeverdProvider>

Data Collection

The SDK automatically collects:

• Device Information: Screen resolution, timezone, language, user agent
• Device Fingerprinting: Canvas, WebGL fingerprints
• Behavioral Biometrics: Typing patterns, mouse movements, scroll behavior
• Session Information: Session duration, page views, interactions

Note: SIM data is not collected for web applications (only for mobile SDKs).

Error Handling

The SDK provides error information through the error property:

const { error } = useKeverdVisitorData();

if (error) {
  switch (error.code) {
    case 'NETWORK_ERROR':
      // Handle network issues
      break;
    case 'INVALID_API_KEY':
      // Handle invalid API key
      break;
    case 'SDK_NOT_INITIALIZED':
      // SDK not initialized
      break;
    default:
      // Handle other errors
  }
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions. All types are exported for use in your code:

import type {
  KeverdConfig,
  KeverdLoadOptions,
  KeverdVisitorData,
  KeverdVisitorDataOptions,
  KeverdVisitorDataHookOptions,
  KeverdVisitorDataResult,
  KeverdDeviceInfo,
  KeverdSessionInfo,
  KeverdBehavioralData,
  KeverdError,
} from '@keverdjs/fraud-sdk-react';

## Next.js Integration

The SDK works seamlessly with Next.js. Wrap your app in `_app.tsx`:

```tsx
// pages/_app.tsx
import type { AppProps } from 'next/app';
import { KeverdProvider } from '@keverdjs/fraud-sdk-react';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <KeverdProvider
      loadOptions={{
        apiKey: process.env.NEXT_PUBLIC_KEVERD_API_KEY!,
      }}
    >
      <Component {...pageProps} />
    </KeverdProvider>
  );
}

export default MyApp;

For Next.js App Router, wrap your root layout:

// app/layout.tsx
import { KeverdProvider } from '@keverdjs/fraud-sdk-react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <KeverdProvider
          loadOptions={{
            apiKey: process.env.NEXT_PUBLIC_KEVERD_API_KEY!,
          }}
        >
          {children}
        </KeverdProvider>
      </body>
    </html>
  );
}

Advanced Usage

Manual Data Collection

You can access the SDK instance directly for manual operations:

import { useKeverdContext } from '@keverdjs/fraud-sdk-react';

function MyComponent() {
  const sdk = useKeverdContext();
  
  const handleManualCheck = async () => {
    const result = await sdk.getVisitorData({ extendedResult: true });
    console.log('Risk assessment:', result);
  };

  return <button onClick={handleManualCheck}>Check Risk</button>;
}

Using Collectors Directly

For advanced use cases, you can use collectors directly:

import { KeverdDeviceCollector, KeverdBehavioralCollector } from '@keverd/fraud-sdk-react';

const deviceCollector = new KeverdDeviceCollector();
const behavioralCollector = new KeverdBehavioralCollector();

// Start collectors
behavioralCollector.start();

// Collect data manually
const deviceInfo = deviceCollector.collect();
const behavioralData = behavioralCollector.getData();

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.