> ## Documentation Index
> Fetch the complete documentation index at: https://doc.youverify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate the Fraud Insights SDK

> Integrate the Youverify Fraud Insights SDK to collect device and behavioral signals on web and mobile.

The Fraud Insights SDK collects device and behavioral signals in the background and sends them to Youverify's Behavioral Service to enrich the risk score. It applies to all platforms, web and mobile, and your users never see it.

> [!NOTE]
>
> This guide applies to every platform you use Fraud Insights on, not just web. The session model, events and configuration below are the same everywhere. The installation steps and code examples use the JavaScript package, `youverify-behavioral-web-sdk`, which you can add to any web application.

## Features

* **Session management**: automatic session IDs and start and end tracking.
* **Device and behavioral signals**: powered by FingerprintJS and browser heuristics.
* **Event tracking**: send custom events with optional user or entity IDs and metadata.
* **Typed responses**: a rich `GetDeviceResponse` structure for risk analysis.

## Installation

> [tab] npm
>
> ```bash theme={null}
> npm install youverify-behavioral-web-sdk
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add youverify-behavioral-web-sdk
> ```

Import the SDK in your application:

```ts theme={null}
import YouverifyBBS, { GetDeviceResponse } from 'youverify-behavioral-web-sdk';
```

## Configuration

Create an instance with `new YouverifyBBS(props)`:

```ts theme={null}
const bbs = new YouverifyBBS({
  publicKey: 'YOUR_PUBLIC_KEY',
  applicationName: 'My Web App',
  sandboxEnvironment: true,
  onLoad: (result: GetDeviceResponse) => {
    console.log('BBS loaded', result.sessionId, result.id);
  },
  onError: (error: Error) => {
    console.error('BBS error', error);
  },
  onSessionStart: (sessionId: string) => {
    console.log('Session started', sessionId);
  },
  onSessionEnd: () => {
    console.log('Session ended');
  },
});
```

### Props

**publicKey** `string` *required*

Your **Public Merchant Key**. You can find it in the **API / Webhook** section of your Youverify dashboard. It is safe to use in client-side code.

**applicationName** `string` *required*

Logical name of the integrating application.

**sandboxEnvironment** `boolean` (default: true)

`true` uses the sandbox (staging) environment. `false` uses production.

**onLoad** `(result: GetDeviceResponse) =\> void`

Called after a successful signal response, for example after `get()`.

**onError** `(error: Error) =\> void`

Called whenever the SDK encounters an error.

**onSessionStart** `(sessionId: string) =\> void`

Called when a session is initialized.

**onSessionEnd** `() =\> void`

Called when `close()` completes and the session ends.

## Core API

### `get(entityId?)`

Initializes or resumes a session and sends the initial signal. Returns `Promise<void>`.

```ts theme={null}
await bbs.get('user-123');
```

* The first call sends a `session_start` event.
* Later calls in the same session send a "Session resumed" custom event.
* It triggers `onLoad(result: GetDeviceResponse)` with the full device and session data.

### `sendEvent(eventTitle, entityId?, meta?)`

Sends a custom behavioral event for the current session. Returns `Promise<void>`.

```ts theme={null}
await bbs.sendEvent('Checkout Started', 'user-123', {
  step: 'payment',
  cartValue: 199.99,
});
```

### `close(entityId?)`

Sends a `session_end` event and clears the local session state. Returns `Promise<void>`.

```ts theme={null}
await bbs.close('user-123');
```

### `getSessionId()`

Returns the current session ID, or `null` if there is none.

```ts theme={null}
const sessionId = bbs.getSessionId();
```

### `getSessionDuration()`

Returns the time in milliseconds since the session started.

```ts theme={null}
const durationMs = bbs.getSessionDuration();
```

## Environments

The SDK chooses backend URLs from the build configuration and the `sandboxEnvironment` flag.

| Setting | Environment |
| - | - |
| `sandboxEnvironment: true` | Sandbox (staging) |
| `sandboxEnvironment: false` | Production |

Use the Public Merchant Key from the **API / Webhook** section of your dashboard, and make sure it matches the environment you are using.

## Usage examples

### Script tag (UMD)

```html theme={null}
<script src="/dist/index.umd.cjs"></script>
<script>
  const bbs = new YouverifyBBS({
    publicKey: 'YOUR_PUBLIC_KEY',
    applicationName: 'Sample Page',
    onLoad: (result) => {
      console.log('Loaded', result.sessionId, result.id);
    },
    onError: (err) => {
      console.error('BBS error', err);
    },
  });

  bbs.get();

  async function sendSampleEvent() {
    await bbs.sendEvent('Sample Button Clicked', 'user-123', {
      source: 'demo',
    });
  }
</script>
```

### React

```tsx theme={null}
import React, { useEffect, useMemo, useState } from 'react';
import YouverifyBBS, { GetDeviceResponse } from 'youverify-behavioral-web-sdk';

export function BBSProvider() {
  const [sessionId, setSessionId] = useState<string | null>(null);
  const [ready, setReady] = useState(false);

  const bbs = useMemo(
    () =>
      new YouverifyBBS({
        publicKey: 'YOUR_PUBLIC_KEY',
        applicationName: 'My React App',
        onSessionStart: setSessionId,
        onLoad: (res: GetDeviceResponse) => {
          setSessionId(res.sessionId);
          setReady(true);
        },
        onError: (err: Error) => {
          console.error('BBS error', err);
        },
      }),
    [],
  );

  useEffect(() => {
    bbs.get();
    return () => {
      bbs.close();
    };
  }, [bbs]);

  const trackClick = async () => {
    await bbs.sendEvent('Button Clicked', 'user-123', { page: 'home' });
  };

  if (!ready) return <div>Loading behavioral signals...</div>;

  return (
    <div>
      <p>Session ID: {sessionId}</p>
      <button onClick={trackClick}>Track behavioral event</button>
    </div>
  );
}
```

## Browser support

* Modern browsers with ES2015+ support.
* Requires the Fetch API, or a polyfill.

> [!NOTE]
>
> Always use the correct Public Merchant Key as your `publicKey` for the environment (sandbox or production). Use meaningful event names and attach `meta` data for richer analytics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.