Verilive JavaScript SDK is a library that allows you to integrate liveness verification into your web application. It provides a simple API to start and manage liveness verification.

Integration Steps

1. Create a session in your backend by making a POST request to /liveness2/session endpoint.

   cURL example:

   curl -X POST https://services.<region>.verigram.kz/liveness2/session \
     -H 'Content-Type: application/json' \
     -H 'X-Verigram-Api-Version: 2.0' \
     -H 'X-Verigram-Api-Key: your-test-api-key' \
     -d '{ "person_id": "end-user-id" }'
   

   The endpoint returns a JSON object containing session_id, access_token, person_id, and flow_id. Pass these values directly to your frontend.

2. In your web application, create a Verilive instance:

   import { Verilive, VeriliveError } from 'verilive-sdk';
   
   const verilive = new Verilive();
   

3. Call the start() method on the Verilive instance using the parameters obtained from your backend.

   try {
     const result = await verilive.start({
       flowId: 'your-flow-id',
       accessToken: 'your-access-token',
       personId: 'your-person-id',
       sessionId: 'your-session-id',
     });
   
     if (result.success) {
       console.log('Verification completed successfully');
       // fetch the final result from your backend using flow_id
     } else {
       console.log('Verification failed:', result.errorCode);
     }
   } catch (error) {
     if (error instanceof VeriliveError) {
       console.error('SDK error:', error.code, error.message);
     } else {
       console.error('Unexpected error:', error);
     }
   }
   

4. Handle the result and errors

   The start() method returns a VeriliveResult with a success flag and an optional errorCode. If success is true, you must fetch the final verdict from your backend using the flow_id. The JavaScript SDK does not provide the liveness verdict directly. This behavior is deliberate; frontend results are not reliable and can be tampered with by an attacker.

   To get the results of the Flow, you need to make a GET request to the endpoint /flow/{flow_id}/result.

   curl -X GET https://services.<region>.verigram.kz/flow/{flow-id}/result \
     -H 'Content-Type: application/json' \
     -H 'X-Verigram-Api-Version: 2.0' \
     -H 'X-Verigram-Api-Key: your-test-api-key'
   

API Reference

Verilive class

Constructor

Creates and returns a new Verilive object.

Syntax:

new Verilive(options?)

Parameters:

options (optional) — An object used to configure the SDK. The available properties are:

• language?: 'ru' | 'kz' | 'en' — Override the browser locale with a specific language (default: browser locale).

• closeOnBackdropClick?: boolean — Determines whether clicking the backdrop closes the modal (default: false).

Example:

const verilive = new Verilive({
  language: 'en',
  closeOnBackdropClick: false,
});

start() method

Initiates the liveness verification process. Returns a Promise that resolves with a VeriliveResult upon completion, or rejects with a VeriliveError if a critical SDK error occurs.

Only one simultaneous start() call is permitted across all Verilive instances. If start() is invoked while another session is already in progress, the SDK will reject the call and throw a VeriliveAlreadyStartedError.

Syntax:

start(params: {
  flowId: string;
  accessToken: string;
  personId: string;
  sessionId: string;
  baseUrl?: string;
  attemptsLeft?: number;
  showStartScreen?: boolean;
  showResultScreen?: boolean;
  language?: 'ru' | 'kz' | 'en';
  onRetry?: (params: OnRetryParams) => Promise<RetryData>;
}): Promise<VeriliveResult>

Parameters:

params — An object containing session and UI configuration:

• flowId: string — Required. The unique identifier for the verification flow, obtained from your backend.

• accessToken: string — Required. Authentication token obtained from the backend to authorize the session.

• personId: string — Required. The unique identifier for the individual undergoing verification.

• sessionId: string — Required. A unique ID for the current attempt.

  Note: Do not rely on this ID for final results; use flowId as it remains constant across retries.

• baseUrl?: string — Optional. Override the default API URL. Required for on-premises deployments.

• attemptsLeft?: number — Optional. Number of retry attempts allowed. When set, after all attempts are exhausted the start() promise resolves with { success: false } and the corresponding errorCode. When not set, retry is managed by the onRetry callback or the server.

• showStartScreen?: boolean — Optional. Whether to display the instruction screen before starting (default: true).

• showResultScreen?: boolean — Optional. Whether to show success/failure feedback screens (default: true).

• language?: 'ru' | 'kz' | 'en' — Optional. Override the language set in the constructor for this session.

• onRetry?: (params: OnRetryParams) => Promise<RetryData> — Optional. Callback for consumer-managed retry. Called when the user clicks retry. Must return new session credentials. If not provided, the SDK handles retry internally.

Return value:

• Promise<VeriliveResult> — Resolves with { success: boolean; errorCode?: string }.

Example:

const result = await verilive.start({
  flowId: 'your-flow-id',
  accessToken: 'your-access-token',
  personId: 'your-person-id',
  sessionId: 'your-session-id',
  baseUrl: 'https://liveness.company.com/',
  showStartScreen: false,
  showResultScreen: false,
});

if (result.success) {
  // Fetch the final verdict from your backend
} else {
  console.log('Failed with error:', result.errorCode);
}

unmount() method

Unmounts the SDK if it is currently running. This interrupts the active liveness process and cleans up all associated resources. If a start() call is still in progress, the associated Promise will be rejected with a VeriliveUnmountedError.

Syntax:

unmount(): void

Example:

setTimeout(() => {
  verilive.unmount();
}, 1000);

try {
  await verilive.start({ flowId, accessToken, personId, sessionId });
} catch (error) {
  // error will be a VeriliveUnmountedError after 1 second
}

Error Handling

The SDK has two levels of errors:

1. Thrown errors (caught with try/catch) — critical SDK failures where the process cannot continue.

2. Result errors (returned in VeriliveResult.errorCode) — business-level errors from the liveness process. The SDK flow completed normally but verification did not pass.

Thrown Errors (Critical)

These errors indicate that the SDK itself encountered a critical problem. They are thrown as exceptions and should be caught with try/catch.

All SDK errors extend from VeriliveError, which includes the following properties:

• code: string — A unique identifier for the specific error type.

• message: string — A human-readable description of the error.

VeriliveAlreadyStartedError

Thrown when start() is invoked while a previous verification is still in progress.

• Code: ALREADY_STARTED

VeriliveCancelledByUserError

Thrown when the user manually cancels the verification (e.g., by pressing the browser back button or Escape key).

• Code: CANCELLED_BY_USER

VeriliveInternalError

Thrown when an internal SDK error occurs, typically due to environment issues or unexpected failures.

• Code: INTERNAL_ERROR

• Common Causes:

  • The document.body is not available at the time of initialization.

  • Communication failure between the main window and the verification iframe.

  • Required browser APIs (like MediaDevices) are missing or restricted.

VeriliveUnmountedError

Thrown when unmount() is called while a verification is in progress.

• Code: UNMOUNTED

Example:

try {
  const result = await verilive.start({
    flowId, accessToken, personId, sessionId,
  });
  // handle result...
} catch (error) {
  if (error instanceof VeriliveError) {
    switch (error.code) {
      case 'ALREADY_STARTED':
        console.error('A verification is already in progress');
        break;
      case 'CANCELLED_BY_USER':
        console.log('User cancelled the verification');
        break;
      case 'INTERNAL_ERROR':
        console.error('Internal SDK error:', error.message);
        break;
      case 'UNMOUNTED':
        console.log('SDK was unmounted');
        break;
    }
  }
}

Result Errors (Business)

These errors are returned in VeriliveResult.errorCode when start() resolves (not throws). The SDK flow completed normally, but the liveness check did not pass.

Example:

const result = await verilive.start({
  flowId, accessToken, personId, sessionId,
});

if (result.success) {
  console.log('Verification passed');
} else {
  switch (result.errorCode) {
    case 'LIVENESS_FAILED':
      console.log('Liveness check failed');
      break;
    case 'SERVER_ERROR':
      console.error('Server error during verification');
      break;
    case 'NETWORK_ERROR':
      console.error('Network error during verification');
      break;
  }
}

Retry Handling

The SDK supports two retry modes:

SDK-managed retry (default)

When the liveness check fails and attemptsLeft > 0, the SDK automatically shows a retry screen and handles the retry internally via the server endpoint.

const result = await verilive.start({
  flowId, accessToken, personId, sessionId,
  attemptsLeft: 3,
});

Consumer-managed retry

Provide an onRetry callback to handle retry logic yourself. The callback receives the current session info and must return new session credentials.

const result = await verilive.start({
  flowId, accessToken, personId, sessionId,
  onRetry: async ({ sessionId, errorCode, attemptsLeft }) => {
    // Request new session credentials from your backend
    const response = await fetch('/api/retry-session', {
      method: 'POST',
      body: JSON.stringify({ sessionId }),
    });
    const data = await response.json();

    return {
      sessionId: data.sessionId,
      accessToken: data.accessToken,
      attemptsLeft: data.attemptsLeft,
    };
  },
});

Usage Examples

React Example

import { Verilive, VeriliveError } from 'verilive-sdk';

const verilive = new Verilive({ language: 'en' });

function App() {
  const startVerification = async () => {
    try {
      const response = await fetch('/api/get-verification-credentials');
      const { flowId, accessToken, personId, sessionId } = await response.json();

      const result = await verilive.start({
        flowId, accessToken, personId, sessionId,
      });

      if (result.success) {
        console.log('Verification passed');
      } else {
        console.log('Verification failed:', result.errorCode);
      }
    } catch (error) {
      if (error instanceof VeriliveError) {
        console.error('SDK error:', error.code, error.message);
      }
    }
  };

  return (
    <div>
      <button onClick={startVerification}>Start Verification</button>
      <button onClick={() => verilive.unmount()}>Stop</button>
    </div>
  );
}

Vanilla JavaScript Example

import { Verilive, VeriliveError } from 'verilive-sdk';

const verilive = new Verilive({ language: 'en' });

async function startVerification() {
  try {
    const response = await fetch('/api/get-verification-credentials');
    const { flowId, accessToken, personId, sessionId } = await response.json();

    const result = await verilive.start({
      flowId, accessToken, personId, sessionId,
    });

    if (result.success) {
      console.log('Verification passed');
    } else {
      console.log('Verification failed:', result.errorCode);
    }
  } catch (error) {
    if (error instanceof VeriliveError) {
      console.error('SDK error:', error.code, error.message);
    }
  }
}

document.getElementById('startButton').addEventListener('click', startVerification);

History Management

The SDK manages the browser history to provide a seamless user experience. Understanding this mechanism is essential for proper integration with your application's routing.

How It Works

When the start() method is invoked, the SDK pushes a new entry onto the browser's history stack. When the liveness process is completed, canceled, or manually interrupted, the SDK automatically restores the previous history state.

If the user presses the browser Back button during the verification process, the SDK intercepts the navigation, cancels the verification, and rejects the start() promise with a VeriliveCancelledByUserError.

State Transitions

• Successful Verification Completion. The SDK ensures the history returns to a clean state after the callback is executed.

• Manual Unmount. If unmount() is called, the SDK manually rolls back the history stack to the state existing prior to initialization.

• Browser Back Button. Pressing "Back" triggers a natural popstate event which the SDK uses to clean up and reject the pending promise with a VeriliveCancelledByUserError.

TypeScript Support

The SDK includes TypeScript type definitions. Import types as needed:

import {
  Verilive,
  VeriliveError,
  type VeriliveConfig,
  type StartParams,
  type VeriliveResult,
  type OnRetryParams,
  type RetryData,
} from 'verilive-sdk';

const config: VeriliveConfig = {
  language: 'en',
};

const verilive = new Verilive(config);