Integrate the Fraud Insights SDK

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.

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

npm
yarn

npm install youverify-behavioral-web-sdk

yarn add youverify-behavioral-web-sdk

Import the SDK in your application:

import YouverifyBBS, { GetDeviceResponse } from 'youverify-behavioral-web-sdk';

Configuration

Create an instance with new YouverifyBBS(props):

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

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.

string

required

Logical name of the integrating application.

boolean

default:"true"

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

(result: GetDeviceResponse) => void

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

(error: Error) => void

Called whenever the SDK encounters an error.

(sessionId: string) => void

Called when a session is initialized.

() => 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>.

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>.

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>.

await bbs.close('user-123');

`getSessionId()`

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

const sessionId = bbs.getSessionId();

`getSessionDuration()`

Returns the time in milliseconds since the session started.

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)

<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

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.

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.

Get Started

Platform Concepts

Implementation Guides

Webhooks & Events

SDKs

Resources

Integrate the Fraud Insights SDK

Features

Installation

Configuration

Props

Core API

`get(entityId?)`

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

`close(entityId?)`

`getSessionId()`

`getSessionDuration()`

Environments

Usage examples

Script tag (UMD)

React

Browser support

​Features

​Installation

​Configuration

​Props

​Core API

​get(entityId?)

​sendEvent(eventTitle, entityId?, meta?)

​close(entityId?)

​getSessionId()

​getSessionDuration()

​Environments

​Usage examples

​Script tag (UMD)

​React

​Browser support

Features

Installation

Configuration

Props

Core API

`get(entityId?)`

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

`close(entityId?)`

`getSessionId()`

`getSessionDuration()`

Environments

Usage examples

Script tag (UMD)

React

Browser support