> ## Documentation Index
> Fetch the complete documentation index at: https://v2.developer.keverd.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# React Quickstart

Get Started using the Keverd React SDK

***

## Overview

In this 5-minute quickstart, you'll add Keverd to a React app and get:

* **Persistent device IDs** that survive incognito, VPNs, and browser clears
* **Real-time risk scores** for every user action
* **Automatic fraud detection** with minimal setup

**No backend setup required** for the frontend integration. Keverd works out-of-the-box with your existing React app.

***

## Prerequisites

* Node.js 16+ and npm
* Your Favorite Code Editor
* A React app (new or existing)
* 5 minutes of your time

<Note>
  This quickstart covers the **frontend setup only**. You'll need a **<u>backend server</u>** to receive and process device identification events for full fraud detection. Check out one of the **<u>backend quickstarts</u>** after completing this.
</Note>

***

## Step 1: Get Your API Key

1. Sign up for a free Keverd account at [dashboard.keverd.com/request-access](https://dashboard.keverd.com/request-access)
2. Navigate to **Settings → API Keys**
3. Copy your **Public API Key** (starts with `pk_live_`)

***

## Step 2: Install the SDK

```bash theme={null}
npm install @keverdjs/react
```

***

## Step 3: Wrap Your App with KeverdProvider

Add the provider at your app's root. This **prepares** Keverd but does **not** trigger API calls yet.

```jsx theme={null}
// App.jsx
import { KeverdProvider } from '@keverdjs/react';

function App() {
  return (
    <KeverdProvider apiKey="pk_live_your_api_key_here">
      <YourApp />
    </KeverdProvider>
  );
}

export default App;
```

***

## Step 4: Initialize Fingerprinting

**Keverd only starts collecting device data and making API calls when a component calls `useKeverd()`**. This is intentional — it gives you control over **when** fingerprinting happens (e.g., on login, checkout, or app mount).

**Basic usage — trigger on component mount:**

```jsx theme={null}
// Any component in your app
import { useKeverd } from '@keverdjs/react';

function CheckoutPage() {
  const { deviceId, riskScore, isLoading, error } = useKeverd();

  if (isLoading) return <div>Loading device profile...</div>;
  if (error) return <div>Failed to identify device. Please refresh.</div>;

  return (
    <div>
      <p>Device ID: {deviceId}</p>
      <p>Risk Score: {riskScore}/100</p>
      <p>Risk Level: {riskScore > 70 ? '⚠️ High' : '✅ Normal'}</p>
    </div>
  );
}
```

***

## How It Works

| Step                     | What Happens                                  | Who Triggers It           |
| ------------------------ | --------------------------------------------- | ------------------------- |
| 1. Provider mounts       | SDK loads, validates API key                  | `KeverdProvider`          |
| 2. Fingerprinting starts | Device signals collected, API call made       | First `useKeverd()` call  |
| 3. Data available        | `deviceId`, `riskScore` returned to component | Hook re-renders with data |

**Key point:** If no component calls `useKeverd()`, Keverd stays idle. No API calls are made. No device data is collected.

***

## Complete Example

```jsx theme={null}
// App.jsx
import { KeverdProvider, useKeverd } from '@keverdjs/react';

function Checkout() {
  const { deviceId, riskScore, isLoading } = useKeverd();

  if (isLoading) return <div>Verifying device...</div>;

  return (
    <div>
      <h1>Checkout</h1>
      <p>Processing payment from device: {deviceId}</p>
      {riskScore > 70 && (
        <p style={{color: 'red'}}>
          ⚠️ High risk detected. Additional verification required.
        </p>
      )}
    </div>
  );
}

function App() {
  return (
    <KeverdProvider apiKey="pk_live_your_api_key_here">
      <Checkout />
    </KeverdProvider>
  );
}

export default App;
```

***

## What About My Backend?

Once `useKeverd()` has resolved, Keverd automatically injects headers into your HTTP requests:

```text theme={null}
// Every fetch/axios request gets these headers:
headers: {
  'X-Keverd-Device-ID': 'vis_2x7f9k3m4n5p8q2r',
  'X-Keverd-Risk-Score': '23',
  'X-Keverd-Session-ID': 'sess_abc123'
}
```

**Backend reads the headers. No backend code changes needed** beyond reading them.

***

## Testing It Works

### 1. Verify the Hook Triggers the Call

Open DevTools Network tab, then mount a component with `useKeverd()`. You should see a request to Keverd's API.

### 2. Check the Console

```js theme={null}
// After useKeverd() resolves:
console.log(window.__KEVERD_DEVICE_ID__);
// Should show: "dev_2x7f9k3m4n5p8q2r"
```

### 3. Test Incognito Persistence

```js theme={null}
// In normal window
await keverd.getDeviceId(); // "dev_2x7f9k3m4n5p8q2r"

// Open incognito, run same code
await keverd.getDeviceId(); // "dev_2x7f9k3m4n5p8q2r" (SAME ID)
```

### 4. View Your Dashboard

Visit [dashboard.keverd.com](https://dashboard.keverd.com) to see devices, risk scores, and blocked attempts.

***

## Common Questions

**Q: Can I trigger fingerprinting without rendering UI?** Yes. Create an invisible component that calls `useKeverd()` on mount, or call the imperative API directly (see [JavaScript Quickstart](https://v2.developer.keverd.com/docs/java-script-1)).

**Q: What if I call `useKeverd()` in multiple components?** The SDK deduplicates — only one API call is made, and all components share the result.

**Q: Does `KeverdProvider` itself make any API calls?** No. It only sets up context. The first `useKeverd()` call triggers all fingerprinting logic.