Youverify Livess Web SDK

> Software Development Kit for Youverify's Liveness Check

Installation

To install, run one of the following commands:

``sh
npm install youverify-liveness-web
`
or

`sh
yarn add youverify-liveness-web
`

Usage

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

`js
import YouverifyLiveness from "youverify-liveness-web";
`

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

`js
const yvLiveness = new YouverifyLiveness(options);
`

> For a list of the valid options, check this out

3. Start the process, like so:

`js
yvLiveness.start();
`

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

`js
const tasks = [{ id: "complete-the-circle" }];
yvLiveness.start(tasks);
`

Full Example:

`js
import YouverifyLiveness from "youverify-liveness-web";

try {
const yvLiveness = new YouverifyLiveness({
tasks: [{ id: "complete-the-circle" }],
});
yvLiveness.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.name | String | No | The name of the brand | undefined | Any string |
| 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 |

$3

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

$3

All API endpoints use the following base URL:

Sandbox base URL:
`
https://api.sandbox.youverify.co
`

Live base URL:
`
https://api.youverify.co
`

$3

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:
`json
{
"Content-Type": "application/json",
"Token": "YOUR_API_KEY"
}
`

Request Body:
`json
{
"publicMerchantID": "your_public_merchant_id",
"metadata": {}
}
`

Response:
`json
{
"sessionId": "generated_session_id_here"
}
`

Error Handling:
- The sessionId should be passed to the SDK constructor

$3

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

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

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

Request Body:
`json
{
"publicMerchantID": "your_public_merchant_id",
"deviceCorrelationId": "unique_device_identifier"
}
`

Response:
`json
{
"authToken": "generated_auth_token_here"
}
`

Error Handling:
- The authToken from the response should be passed as sessionToken to the SDK constructor

$3

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

$3

- 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

$3

- 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

$3

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

`javascript
// 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);

// Handle specific error cases
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();
`

$3

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!

$3

User passes task by completing imaginary circle with head movement.

#### Options
| Option | Type | Required | Description | Default Value | Possible Values |
| --- | --- | --- | --- | --- | --- |
id | String | Yes | Id of task | - | complete-the-circle |
difficulty | String | No | Sets difficulty of task | medium | easy, medium, hard |
timeout | Number | No | Sets time in milliseconds after which task automatically fails | undefined | Any number in milliseconds |

$3

User passes task by answering a list of arbitrary questions set by you with the tilting of the head; right for a yes and left for a no.

#### Options
| Option | Type | Required | Description | Default Value | Possible Values |
| --- | --- | --- | --- | --- | --- |
| id | String | Yes | Id of task | - | yes-or-no |
| difficulty | String | No | Sets difficulty of task | medium | easy, medium, hard |
| timeout | Number | No | Sets time in milliseconds after which task automatically fails | undefined | Any number in milliseconds |
| questions | Array | No | A set of questions to ask user | undefined | See nested options below
| questions.question | String | Yes | Question to ask user. Should be a true or false type question. Eg: "Are you ready" | - | Any string
| questions.answer | Boolean | Yes | Answer to the question | - | true, false |
| questions.errorMessage | String | No | Error message to display if user gets question wrong | undefined | Any string |

$3

User passes task by performing random motions in random sequences, which include nodding, blinking and opening of mouth.

#### Options
| Option | Type | Required | Description | Default Value | Possible Values |
| --- | --- | --- | --- | --- | --- |
| id | String | Yes | Id of task | - | motions |
| difficulty | String | No | Sets difficulty of task | medium | easy, medium, hard |
| timeout | Number | No | Sets time in milliseconds after which task automatically fails | undefined | Any number in milliseconds |
| maxNods | Number | No | Maximum amount of nods a user is asked to perform | 5 | Any number
| maxBlinks | Number | No | Maximum amount of nods a user is asked to perform | 5 | Any number |




$3

User passes task by blinking their eyelids based on number of times set.

#### Options
| Option | Type | Required | Description | Default Value | Possible Values |
| --- | --- | --- | --- | --- | --- |
| id | String | Yes | Id of task | - | blink |
| difficulty | String | No | Sets difficulty of task | medium | easy, medium, hard |
| timeout | Number | No | Sets time in milliseconds after which task automatically fails | undefined | Any number in milliseconds |
| maxBlinks | Number | No | Maximum amount of nods a user is asked to perform | 5 | Any number |

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 |
| data.error | Object | Error object containing error key(eyes_closed, image_capture_failed, API_ERROR`) and message (only present in failure cases) |

Credits

This SDK is developed and maintained solely by Youverify