Youverify Behavioral Web SDK

An SDK for Youverify's Behavioral Service that can be used as a third‑party library in any web application.

Features

• Session management – automatic session IDs, start/end tracking.
• Device & behavioral signals – powered by FingerprintJS and browser heuristics.
• Event tracking – send custom events with optional user/entity IDs and metadata.
• Typed responses – rich GetDeviceResponse structure for risk analysis.

Installation

From npm (recommended)

npm install youverify-behavioral-web-sdk
# or
yarn add youverify-behavioral-web-sdk

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

Building the SDK

From the behavioural-service-web-sdk directory:

yarn install
yarn build

Configuration (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

• publicKey: string (required)
  Business public key provided by Youverify.

• applicationName: string (required)
  Logical name of the integrating application.

• sandboxEnvironment?: boolean (default: true)

  • true → Sandbox / staging environment.
  • false → Production environment.

• onLoad?: (result: GetDeviceResponse) => void
  Called after a successful signal response (e.g. 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?: string): Promise<void>

Initialize or resume a session and send the initial signal.

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

• First call sends a session_start event.
• Subsequent calls in the same session send a “Session resumed” custom event.
• Triggers onLoad(result: GetDeviceResponse) with full device/session data.

sendEvent(eventTitle: string, entityId?: string, meta?: Record<string, any>): Promise<void>

Send a custom behavioral event for the current session.

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

close(entityId?: string): Promise<void>

Send a session_end event and clear local session state.

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

getSessionId(): string | null

Get the current session ID, or null if none:

const sessionId = bbs.getSessionId();

getSessionDuration(): number

Get the session duration in milliseconds since it started:

const durationMs = bbs.getSessionDuration();

Environments

The SDK chooses backend URLs based on configuration in the build and the sandboxEnvironment flag:

| Setting | Description | | --------------------------- | ----------------- | | sandboxEnvironment: true | Sandbox / staging | | sandboxEnvironment: false | Production |

Your backend team will tell you which combination and public key to use in each environment.

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 example

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 Fetch API (or a polyfill).

Notes

• Always use the correct publicKey for the environment (sandbox/prod).
• Prefer meaningful event names and attach meta data for richer analytics.