youverify-liveness-web/README.md

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

# Youverify 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-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](#options) 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 | 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!

### Complete The Circle

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 |

### Yes Or No

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 |

### Motions

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 |

## 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)