youverify-passive-liveness-web/README.md

> Software Development Kit for [Youverify](https://youverify.co)'s Liveness Check

# Youverify Passive Livess Web SDK

> Software Development Kit for [Youverify](https://youverify.co)'s Liveness Check

## Installation

To install, run one of the following commands:

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

or

```sh
yarn add youverify-passive-liveness-web
```

## Usage

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

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

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

```js
const yvPassiveLiveness = new YouverifyPassiveLiveness(options);
```

> For a list of the valid options, check [this](#options) out

3. Start the process, like so:

```js
yvPassiveLiveness.start();
```

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

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

Full Example:

```js
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 | Yes | 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](#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 |
| `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](#callback-data) | undefined | Any valid function |
| `onFailure` | Function | No | Callback function that gets triggered when at least one task fails. Called with completion [data](#callback-data) | undefined | Any valid function |

## 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](https://youverify.co).