Web

The Youverify Liveness Web SDK adds anti-deepfake liveness detection to your web application without redirecting users to a hosted page. Users complete one or more short tasks, such as tracing a circle with their head, and the SDK returns the result to your callbacks.

Installation

npm
Yarn
CDN (jsDelivr)
CDN (UNPKG)

npm install youverify-liveness-web

yarn add youverify-liveness-web

<script src="https://cdn.jsdelivr.net/npm/youverify-liveness-web/dist/index.js"></script>

<!-- Latest version -->
<script src="https://unpkg.com/youverify-liveness-web/dist/index.js"></script>

<!-- Pinned version -->
<script src="https://unpkg.com/youverify-liveness-web@1.2.3/dist/index.js"></script>

Integration steps

Generate a session ID and a session token on your backend

The SDK doesn’t generate session tokens itself. Your backend calls the Youverify API with your secret API key and passes both values to the page. See Generate the session ID and session token.

Import and initialize the SDK

import YouverifyLiveness from "youverify-liveness-web";

const yvLiveness = new YouverifyLiveness(options);

For the valid options, see Options.

Start the liveness check

yvLiveness.start();

You can also pass an array of tasks. Tasks passed to start() override the tasks you set during initialization.

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

Generate the session ID and session token

Both calls must come from your backend. Use the base URL for the environment you are testing against.

Environment	Base URL
Sandbox	`https://api.sandbox.youverify.co`
Live	`https://api.youverify.co`

Never expose your API key in frontend code. Make these calls from your secure backend.

Session ID

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"
}

Pass the sessionId to the SDK constructor.

Session token

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"
}

Pass the authToken to the SDK constructor as sessionToken. The deviceCorrelationId should be a unique identifier for the user’s device or session. It helps track and prevent abuse.

Full example

import YouverifyLiveness from "youverify-liveness-web";

try {
  const yvLiveness = new YouverifyLiveness({
    sessionId: sessionId,        // from your backend
    sessionToken: sessionToken,  // from your backend
    sandboxEnvironment: true,    // set to false for production
    tasks: [{ id: "complete-the-circle" }],
    onSuccess: (data) => {
      console.log("Liveness check passed:", data);
    },
    onFailure: (data) => {
      console.log("Liveness check failed:", data);

      if (data.error?.key === "invalid_or_expired_session") {
        // Generate a new session and retry
      } else if (data.error?.key === "session_token_error") {
        // Generate a new session token and retry
      }
    },
  });

  yvLiveness.start();
} catch (error) {
  // Handle validation errors
  console.log(`Something isn't right, ${error}`);
}

Preloading

The SDK downloads its face detection model, several MB, before the liveness check can begin. The download doesn’t depend on the session, so start it early, before you generate the sessionId and sessionToken.

import YouverifyLiveness from "youverify-liveness-web";

YouverifyLiveness.preload();

It’s safe to call more than once. Later calls, including the one the constructor makes, reuse the download already in progress.
If you don’t call it, the download starts when the SDK is constructed.
preload() keeps the detector in memory, so it only carries over to the liveness check if the page isn’t reloaded in between. That’s the case in single-page apps that navigate with their router.

Single-page apps

Call preload() in your app’s entry module.

Framework	Where to call `preload()`
React / Preact (Vite, CRA)	`main.tsx` / `index.tsx`, before `render`
Vue	`main.ts`, before `createApp(...).mount()`
Angular	`main.ts`, before `bootstrapApplication`
Next.js	A client component in the root layout (or `_app`), inside `useEffect`

// main.tsx
import YouverifyLiveness from "youverify-liveness-web";

YouverifyLiveness.preload();

createRoot(document.getElementById("root")).render(<App />);

A reload cancels any download still in progress. Files that already finished come from the browser’s HTTP cache, and anything that was cut off downloads again as soon as the entry module runs.

Multi-page sites

If users reach the liveness check through full page loads, the preloaded detector is discarded on every navigation. Call prefetch() on the pages before the liveness check instead.

YouverifyLiveness.prefetch();

It asks the browser to download the detector files into its HTTP cache in the background, without building the detector. When the SDK starts on the liveness page, the files come from the cache. The detector is still set up on that page, so this saves download time but not setup time.

It’s safe to call on every page. Files already requested aren’t added again.
It relies on the browser’s HTTP cache. It has no effect if caching is disabled, for example in a webview configured with LOAD_NO_CACHE.
<link rel="prefetch"> is supported in Chromium-based browsers and Firefox, but not in Safari, where prefetch() does nothing.

Your app	Call	Result on the liveness page
Single-page app	`preload()` once in the app entry module	Detector ready, if it finished loading before the user got there
Multi-page site	`prefetch()` on earlier pages	Files come from cache; detector still set up there

Options

string

required

ID generated by your backend using your API key. The SDK validates it before initialization and attaches it to submissions.

string

required

Token generated by your backend for liveness verification.

string

Your Youverify public merchant key.

boolean

default:"true"

Whether the session runs in sandbox or live mode. Set to false for production.

string

default:"modal"

How the UI is displayed. One of modal or page.

array

The tasks the user must perform to confirm liveness. See Tasks.

string

Optional entity identifier to include when the liveness result is submitted.

boolean

default:"false"

Whether to narrate information to the user during tasks.

object

Details of the user being checked.

Show properties

string

required

First name of the user.

string

Last name of the user.

string

Email of the user.

object

Customizes the UI to fit your brand.

Show properties

string

The name of the brand.

string

Your branding color, as a valid hex or RGB string.

string

A link to your logo image.

string

default:"Youverify"

Alternative text for the brand logo.

boolean

default:"false"

Hides the logo in a mobile webview.

boolean

default:"false"

Shows the “Powered by” footer text.

string

default:"Powered by"

Customizes the “Powered by” text.

string

A link to a custom “Powered by” logo image.

function

Called when the modal is closed.

function

Called when all tasks have been completed and passed. Receives the callback data.

function

Called when at least one task fails. Receives the callback data.

Tasks

A task is a series of instructions the user follows to confirm liveness. Pass tasks in the tasks option or to start(). Every task takes these options:

Option	Type	Required	Description	Default
`id`	String	Yes	ID of the task. See the sections below.	-
`difficulty`	String	No	`easy`, `medium` or `hard`	`medium`
`timeout`	Number	No	Time in milliseconds after which the task fails automatically	undefined

Complete the Circle

The user completes an imaginary circle with head movement. Use id: "complete-the-circle".

Yes or No

The user answers questions you set by tilting their head: right for yes, left for no. Use id: "yes-or-no".

Option	Type	Required	Description
`questions`	Array	No	The questions to ask the user
`questions.question`	String	Yes	A true-or-false question, for example “Are you ready”
`questions.answer`	Boolean	Yes	The correct answer, `true` or `false`
`questions.errorMessage`	String	No	Message shown if the user answers wrongly

Motions

The user performs random motions in random sequences: nodding, blinking and opening the mouth. Use id: "motions".

Option	Type	Required	Description	Default
`maxNods`	Number	No	Maximum number of nods the user is asked to perform	5
`maxBlinks`	Number	No	Maximum number of blinks the user is asked to perform	5

Blink

The user blinks a set number of times. Use id: "blink".

Option	Type	Required	Description	Default
`maxBlinks`	Number	No	Maximum number of blinks the user is asked to perform	5

Callback data

onSuccess and onFailure receive an object with these properties.

boolean

Whether the liveness check passed.

string

Face image of the user performing the check.

string

Video of the user performing the check.

any

Metadata passed in during initialization.

object

Present only on failure. Contains key (eyes_closed, image_capture_failed or API_ERROR) and message.

When the SDK submits the liveness payload, it includes sdkVersion (the SDK package version, 1.2.3) and, if you passed it during initialization, entityId.

Errors and retries

Error key	Meaning
`invalid_or_expired_session`	The `sessionId` is invalid or expired
`session_token_error`	There is a problem with the `sessionToken` during liveness verification

If session validation fails, generate a new sessionId and retry.
If liveness fails, the user can retry while the current sessionId remains valid.
If the sessionId expires, create a new session and restart the process.

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

For the token endpoints shared by all SDKs, see Session tokens.

Get Started

Platform Concepts

Implementation Guides

Webhooks & Events

SDKs

Resources

Installation

Integration steps

Generate the session ID and session token

Session ID

Session token

Full example

Preloading

Single-page apps

Multi-page sites

Options

Tasks

Complete the Circle

Yes or No

Motions

Blink

Callback data

Errors and retries

​Installation

​Integration steps

​Generate the session ID and session token

​Session ID

​Session token

​Full example

​Preloading

​Single-page apps

​Multi-page sites

​Options

​Tasks

​Complete the Circle

​Yes or No

​Motions

​Blink

​Callback data

​Errors and retries

Installation

Integration steps

Generate the session ID and session token

Session ID

Session token

Full example

Preloading

Single-page apps

Multi-page sites

Options

Tasks

Complete the Circle

Yes or No

Motions

Blink

Callback data

Errors and retries