React SDK

npm (Recommended)

Install the React SDK using npm, the Node.js package manager. This is the recommended installation method for most React projects.

npm install @keverdjs/fraud-sdk-react

yarn

Alternatively, install using Yarn if you prefer it over npm.

yarn add @keverdjs/fraud-sdk-react

Peer Dependencies

The React SDK requires React 16.8.0 or higher (for hooks support) and React DOM 16.8.0 or higher. These should already be installed in your React project, but if not, install them:

npm install react react-dom
# or
yarn add react react-dom

Note: The SDK uses React hooks (useState, useEffect, useCallback, useContext) internally, so React 16.8.0+ is required. The SDK is compatible with both class components and function components, but hooks can only be used in function components.

1. Wrap Your App with KeverdProvider

The KeverdProvider component initializes the SDK and provides it to all child components via React Context. Wrap your root component (or the highest component that needs access to the SDK) with KeverdProvider.

Important: The endpoint must use HTTPS. The SDK will throw an error if you provide an HTTP URL. The default API endpoint is https://api.keverd.com.

For Next.js: Place the provider in your _app.tsx or _app.js file. For Create React App or other React setups, place it in your root App.js or index.js.

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

// Next.js: _app.tsx or _app.js
function MyApp({ Component, pageProps }) {
  return (
    <KeverdProvider
      loadOptions={{
        apiKey: process.env.NEXT_PUBLIC_KEVERD_API_KEY, // Use environment variables
        endpoint: 'https://api.keverd.com', // Optional: defaults to https://api.keverd.com
        debug: process.env.NODE_ENV === 'development', // Enable debug in dev only
      }}
    >
      <Component {...pageProps} />
    </KeverdProvider>
  );
}

export default MyApp;

2. Use the Hook in Your Components

The useKeverdVisitorData hook provides a React-friendly interface for accessing visitor data and risk assessment. The hook manages loading states, error handling, and data fetching automatically.

Performance: Data collection typically completes in under 50ms. The total time (including network request) is typically under 200ms (p99 latency). The hook uses React's state management to prevent unnecessary re-renders.

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

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

  // Handle loading state
  if (isLoading) {
    return <div>Loading risk assessment...</div>;
  }

  // Handle error state
  if (error) {
    return (
      <div>
        <p>Error: {error.message}</p>
        <button onClick={() => getData({ ignoreCache: true })}>
          Retry
        </button>
      </div>
    );
  }

  // Handle success state
  return (
    <div>
      <button onClick={() => getData({ ignoreCache: true })}>
        Reload data
      </button>
      <p>Visitor ID: {data?.visitorId}</p>
      <p>Risk Score: {data?.riskScore}/100</p>
      <p>Action: {data?.action}</p>
      <p>Reasons: {data?.reasons.join(', ')}</p>
      
      {/* Handle risk score */}
      {data && data.riskScore >= 70 && (
        <div className="alert alert-warning">
          High risk detected. Additional verification required.
        </div>
      )}
    </div>
  );
}

Network Errors

Network errors occur when the device cannot connect to the API or when the request times out. The SDK uses 30-second timeouts for connection, read, and write operations.

const { isLoading, error, data, getData } = useKeverdVisitorData({
  immediate: true,
});

useEffect(() => {
  if (error) {
    if (error.message.includes('timeout') || error.message.includes('Timeout')) {
      // Handle timeout - retry with exponential backoff
      console.warn('Request timed out, retrying...');
      setTimeout(() => getData({ ignoreCache: true }), 1000);
    } else if (error.message.includes('network') || error.message.includes('Network')) {
      // Handle network connectivity issues
      console.error('Network error:', error.message);
      showNetworkError();
    }
  }
}, [error, getData]);

API Errors

API errors occur when the server returns an error status code (4xx or 5xx). Common causes include invalid API keys, rate limiting, or server errors.

useEffect(() => {
  if (error) {
    if (error.message.includes('401') || error.message.includes('Unauthorized')) {
      // Invalid API key
      console.error('Invalid API key. Please check your configuration.');
      showConfigurationError();
    } else if (error.message.includes('429') || error.message.includes('rate limit')) {
      // Rate limit exceeded
      console.warn('Rate limit exceeded. Please retry after some time.');
      showRateLimitError();
    } else if (error.message.includes('500') || error.message.includes('502') || error.message.includes('503')) {
      // Server errors - retry with backoff
      console.error('Server error:', error.message);
      retryWithBackoff();
    } else {
      // Other API errors
      console.error('API error:', error.message);
      handleApiError(error);
    }
  }
}, [error]);

SDK Not Ready Errors

These errors occur when you try to use the SDK before it's initialized or when the provider hasn't mounted yet.

const { isLoading, error, data, getData } = useKeverdVisitorData({
  immediate: true,
});

useEffect(() => {
  if (error && error.code === 'SDK_NOT_READY') {
    // SDK not initialized - wait a bit and retry
    console.warn('SDK not ready, retrying...');
    setTimeout(() => getData({ ignoreCache: true }), 100);
  }
}, [error, getData]);

Best Practices for Error Handling

• Use useEffect to monitor errors: Set up a useEffect hook to monitor the error state and handle errors appropriately.
• Implement retry logic: For transient errors (network timeouts, server errors), implement retry logic with exponential backoff.
• Fail gracefully: Decide on a fail-open or fail-closed strategy. Fail-open allows access when the SDK fails, while fail-closed blocks access. Choose based on your security requirements.
• Log errors: Log errors to your error tracking service (e.g., Sentry, LogRocket) for debugging and monitoring.
• User feedback: Provide clear feedback to users when errors occur, especially for authentication or security-related failures.

Provider Setup

• Place provider high in component tree: Place the KeverdProvider as high as possible in your component tree (ideally at the root level) to ensure all components have access to the SDK.
• Use environment variables: Store your API key in environment variables and never commit it to version control. Use different API keys for development, staging, and production environments.
• Enable debug in development only: Set debug: true only in development environments. Disable it in production to avoid exposing sensitive information in the console.

Hook Usage

• Use immediate option wisely: Set immediate: true only when you need data immediately on component mount. For on-demand fetching, use immediate: false and call getData() manually.
• Avoid excessive calls: Don't call getData() on every render or user interaction. Use it strategically for high-value or high-risk operations.
• Handle loading and error states: Always handle the isLoading and error states in your components to provide good user experience.

Security

• Protect your API key: Never expose your API key in client-side code that can be viewed in the browser. Use environment variables or a secure configuration management system.
• Use HTTPS: Always use HTTPS endpoints. The SDK will not work with HTTP endpoints for security reasons.
• Validate risk scores: Don't blindly trust risk scores. Use them as one factor in your security decision-making process, along with other signals.
• Monitor for anomalies: Set up monitoring and alerting for unusual patterns in risk scores or error rates.

Performance

• Non-blocking: The SDK is designed to be non-blocking. Data collection and API calls happen asynchronously and won't block your UI.
• Minimal impact: Behavioral data collection is passive and has minimal impact on page performance. The SDK uses efficient event listeners that are automatically cleaned up.
• Bundle size: The SDK is lightweight and has a small bundle size. It won't significantly impact your application's load time.

Privacy and Compliance

• GDPR compliance: The SDK is designed to be GDPR-compliant. All sensitive data is hashed client-side, and no PII is collected or transmitted.
• User consent: Consider obtaining user consent before initializing the SDK, especially in regions with strict privacy regulations.
• Privacy policy: Update your privacy policy to inform users about data collection and how it's used for fraud detection.