Youverify Passive Livess Web SDK

Software Development Kit for Youverify's Liveness Check

Installation

To install, run one of the following commands:

npm install youverify-passive-liveness-web

or

yarn add youverify-passive-liveness-web

Usage

1. Import the package into your web page like so:

import YouverifyLivenessPassive from "youverify-passive-liveness-web";

2. Initialize an instance of the package, like so:

const yvPassiveLiveness = new YouverifyPassiveLiveness(options);

For a list of the valid options, check this out

3. Start the process, like so:

yvPassiveLiveness.start();

This could also be called with an array of tasks. The supplied tasks override those provided during initialization.

const tasks = [{ id: "passive" }];
yvPassiveLiveness.start(tasks);

Full Example:

import YouverifyPassiveLiveness from "youverify-passive-liveness-web";

try {
  const yvPassiveLiveness = new YouverifyPassiveLiveness({
    tasks: [{ id: "passive" }],
  });
  yvPassiveLiveness.start();
} catch (error) {
  // Handle Validation Errors
  console.log(`Something isn't right, ${error}`);
}

Options

| Option | Type | Required | Description | Default Value | Possible Values | | --- | --- | --- | --- | --- | --- | | presentation | String | No | Controls how UI is displayed | modal | modal, page | | publicKey | String | No | Your Youverify Public Merchant Key | undefined | Valid Youverify Public Key | | sandboxEnvironment | Boolean | No | Sets whether session should run in sandbox or live mode | true | true, false | | tasks | Array | No | Sets tasks that need to be performed for liveness to be confirmed | undefined | See tasks | | user | Object | No | Sets details of user for which liveness check is being performed | undefined | See nested options below | | user.firstName | String | Yes | First name of user | - | Any string | | user.lastName | String | No | Last name of user | undefined | Any string | user.email | String | No | Email of user | undefined | Any string | | branding | Object | No | Customizes UI to fit your brand | undefined | See nested options below | branding.color | String | No | Sets your branding color | undefined | Valid hex or RGB string | | branding.logo | String | No | Sets your logo | undefined | Valid image link | | branding.logoAlt | String | No | Alternative text for the brand logo | "Youverify" | Any string | | branding.hideLogoOnMobile | Boolean | No | Hides logo in mobile webview | false | true, false | | branding.showPoweredBy | Boolean | No | Displays "Powered by" footer text | false | true, false | | branding.poweredByText | String | No | Customizes the "Powered by" text | "Powered by" | Any string | | branding.poweredByLogo | String | No | Customizes the "Powered by" logo | undefined | Valid image link | | allowAudio | Boolean | No | Sets whether to narrate information to user during tasks | false | true, false | | onClose | Function | No | Callback function that gets triggered when modal is closed | undefined | Any valid function | | onSuccess | Function | No | Callback function that gets triggered when all tasks have been completed and passed. Called with completion data | undefined | Any valid function | | onFailure | Function | No | Callback function that gets triggered when at least one task fails. Called with completion data | undefined | Any valid function | | sessionId | String | Yes (required) | ID generated by your backend using your API key. Validated before SDK init and attached to submissions | - | Any valid session ID | | sessionToken | String | Yes (required) | Token generated by your backend for liveness verification | - | Any valid session token |

Breaking change: session token generation now external

• The SDK no longer generates session tokens internally.
• Partners must call their backend to generate both sessionId and sessionToken and pass them to the SDK via the respective options.

Base URL Configuration

All API endpoints use the following base URL:

Sandbox base URL:

https://api.sandbox.youverify.co

Live base URL:

https://api.youverify.co

Session ID Generation

Before initializing the SDK, you must generate a sessionId by calling your backend API. Your backend should make the following request:

Endpoint: POST /v2/api/identity/sdk/session/generate

Headers:

{
  "Content-Type": "application/json",
  "Token": "YOUR_API_KEY"
}

Request Body:

{
  "publicMerchantID": "your_public_merchant_id",
  "metadata": {}
}

Response:

{
  "sessionId": "generated_session_id_here"
}

Error Handling:

• The sessionId should be passed to the SDK constructor

Session Token Generation

Additionally, you need to generate a sessionToken for liveness verification:

Endpoint: POST /v2/api/identity/sdk/liveness/token

Headers:

{
  "Content-Type": "application/json",
  "Token": "YOUR_API_KEY"
}

Request Body:

{
  "publicMerchantID": "your_public_merchant_id",
  "deviceCorrelationId": "unique_device_identifier"
}

Response:

{
  "authToken": "generated_auth_token_here"
}

Error Handling:

• The authToken from the response should be passed as sessionToken to the SDK constructor

Complete Integration Flow

1. Generate Session ID: Call your backend to generate sessionId using the session generation endpoint
2. Generate Session Token: Call your backend to generate sessionToken using the liveness token endpoint
3. Initialize SDK: Pass both sessionId and sessionToken to the SDK constructor
4. SDK Validation: The SDK validates the sessionId before initialization
5. Error Handling: If validation fails, onFailure is called with key invalid_or_expired_session and session_token_error for both
6. Success: Upon successful initialization, the SDK uses the sessionToken for liveness verification

Error Keys

• invalid_or_expired_session: Returned when the sessionId is invalid or expired
• session_token_error: Returned when there's an issue with the sessionToken during liveness verification

Retry Logic

• If session validation fails, generate a new sessionId and retry
• If liveness fails, users may retry while the current sessionId remains valid
• If the sessionId expires, create a new session and restart the entire process

Complete Example Implementation

Here's a complete example showing how to implement the session generation and SDK initialization:

// Backend API calls (these should be made from your backend)
const generateSessionId = async (publicMerchantID, apiToken) => {
  const response = await fetch('https://api.sandbox.youverify.co/v2/api/identity/sdk/session/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Token': `${apiToken}`
    },
    body: JSON.stringify({
      publicMerchantID: publicMerchantID,
      metadata: {}
    })
  });

  const data = await response.json();
  return data.sessionId;
};

const generateSessionToken = async (publicMerchantID, deviceCorrelationId, apiToken) => {
  const response = await fetch('https://api.sandbox.youverify.co/v2/api/identity/sdk/liveness/token', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Token': `${apiToken}`
    },
    body: JSON.stringify({
      publicMerchantID: publicMerchantID,
      deviceCorrelationId: deviceCorrelationId
    })
  });

  const data = await response.json();
  return data.authToken;
};

// Frontend SDK initialization
const initializeLivenessSDK = async () => {
  try {
    // Generate session ID and token (these calls should be made from your backend)
    const sessionId = await generateSessionId('your_public_merchant_id', 'your_api_key');
    const sessionToken = await generateSessionToken('your_public_merchant_id', 'unique_device_id', 'your_api_key');

    // Initialize the SDK with generated credentials
    const yvLiveness = new YouverifyLiveness({
      sessionId: sessionId,
      sessionToken: sessionToken,
      sandboxEnvironment: true,
      onSuccess: (data) => {
        console.log('Liveness check passed:', data);
        // Handle successful liveness check
      },
      onFailure: (data) => {
        console.log('Liveness check failed:', data);

        if (data.error && data.error.key === 'invalid_or_expired_session') {
          // Session expired, generate new session and retry
          console.log('Session expired, retrying...');
          initializeLivenessSDK();
        } else if (data.error && data.error.key === 'session_token_error') {
          // Session token error, generate new token and retry
          console.log('Session token error, retrying...');
          initializeLivenessSDK();
        }
      }
    });

    // Start the liveness check
    yvLiveness.start();

  } catch (error) {
    console.error('Failed to initialize liveness SDK:', error);
    // Handle initialization errors
  }
};

// Call the initialization function
initializeLivenessSDK();

Important Notes

1. API Token Security: Never expose your API token in frontend code. All API calls to generate sessionId and sessionToken should be made from your secure backend.

2. Device Correlation ID: The deviceCorrelationId should be a unique identifier for the user's device/session. This helps track and prevent abuse.

3. Error Handling: Always implement proper error handling for both API calls and SDK initialization to provide a smooth user experience.

4. Environment: Use sandboxEnvironment: true for testing and sandboxEnvironment: false for production.

Tasks

A task is a series of instructions for users to follow to confirm liveness. Find below a list of tasks.

PS: We aim to frequently add to this list a variety of fun and yet intuitive ways of confirming liveness, so be on the lookout for more tasks!

Passive

User passes task doing nothing.

Options

| Option | Type | Required | Description | Default Value | Possible Values | | --- | --- | --- | --- | --- | --- | id | String | Yes | Id of task | - | passive |

Callback Data

The onSuccess and onFailure callbacks (if supplied) are passed the following data:

| Option | Type | Description | | --- | --- | --- | | data | Object | Data passed through callback | | data.faceImage | String | Face Image of user performing liveness check | | data.livenessClip | String | Video of user performing liveness check | | data.passed | Boolean | Indicator on whether liveness check passed or failed | | data.metadata | Any | Metadata passed in during initialization |

Credits

This SDK is developed and maintained solely by Youverify.