> ## Documentation Index
> Fetch the complete documentation index at: https://doc.youverify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrate Youverify Web SDK for Browser-Based Verification

> Add identity verification and liveness detection to your web application with the Youverify Web SDK.

The Youverify Web SDK lets you embed liveness detection and document capture directly in your web application — no redirect to a hosted page required. The SDK is compatible with all major browsers and devices. Before launching any SDK flow you must generate a session token from your backend to keep your secret API key off the client.

## Installation

Choose either the npm package or the CDN script tag, depending on whether your project uses a Node.js-based build pipeline.

<Tabs>
  <Tab title="npm">
    Install the package for your chosen flow:

    ```bash theme={null}
    # Liveness detection
    npm install youverify-liveness-web

    # Document capture
    npm install youverify-sdk
    ```
  </Tab>

  <Tab title="CDN (jsDelivr)">
    Add the script tag directly to your HTML if you are not using a Node.js build pipeline:

    ```html theme={null}
    <!-- Liveness Web SDK -->
    <script src="https://cdn.jsdelivr.net/npm/youverify-liveness-web/dist/index.js"></script>

    <!-- Document Capture SDK -->
    <script src="https://cdn.jsdelivr.net/npm/youverify-sdk/dist/index.js"></script>
    ```
  </Tab>

  <Tab title="CDN (UNPKG)">
    ```html theme={null}
    <!-- Liveness Web SDK (latest) -->
    <script src="https://unpkg.com/youverify-liveness-web/dist/index.js"></script>

    <!-- Liveness Web SDK (pinned version) -->
    <script src="https://unpkg.com/youverify-liveness-web@1.0.1/dist/index.js"></script>
    ```
  </Tab>
</Tabs>

## Integration steps

<Steps>
  <Step title="Generate a session ID server-side">
    Your backend calls the Youverify API to generate a short-lived session ID. This call uses your secret API key — it must happen on your server, not in the browser.

    ```bash theme={null}
    curl -X POST "https://api.youverify.co/v2/api/sdk/session-id" \
      -H "token: $YV_SECRET_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "publicMerchantID": "YOUR_PUBLIC_MERCHANT_ID",
        "metadata": {}
      }'
    ```

    Response:

    ```json theme={null}
    {
      "success": true,
      "statusCode": 200,
      "message": "SDK session generated",
      "data": {
        "sessionId": "200f5a883713b7ff26f22f489d716ca3",
        "expiresAt": "2025-10-05T23:56:48.821Z",
        "status": "active"
      },
      "links": []
    }
    ```
  </Step>

  <Step title="Pass the session ID to your front-end">
    Return the `sessionId` from your backend API to the browser. You might expose a thin endpoint on your own server for the browser to call, for example `GET /api/verification-session`.
  </Step>

  <Step title="Initialize the SDK">
    Construct the SDK instance with your public merchant key and the session ID. Register your callbacks before calling `launch()`.

    ```javascript theme={null}
    const yvSDK = new YouverifySDK({
      publicMerchantKey: 'YOUR_PUBLIC_MERCHANT_KEY',
      sessionId: sessionId,         // from your backend
      sandboxEnvironment: false,    // set to true for testing
      onSuccess: (data) => {
        console.log('Verification complete', data);
        // Update your UI and notify your backend
      },
      onError: (error) => {
        console.error('Verification failed', error);
      },
      onClose: () => {
        console.log('User closed the verification flow');
      }
    });
    ```
  </Step>

  <Step title="Launch the verification flow">
    Call `launch()` when your user is ready to start — for example, on a button click.

    ```javascript theme={null}
    document.getElementById('verify-btn').addEventListener('click', () => {
      yvSDK.launch();
    });
    ```
  </Step>
</Steps>

## Callbacks

| Callback | When it fires | Argument |
| - | - | - |
| `onSuccess` | All verification tasks completed successfully | Result data object |
| `onError` | A task failed or an error occurred | Error object with `key` and `message` |
| `onClose` | The user dismissed the SDK modal | None |

## Configuration options

<ParamField body="publicMerchantKey" type="string" required>
  Your Youverify public merchant key. Safe to embed in browser code. Retrieve it from **Settings → API KEY / Webhook** in the Cowork dashboard.
</ParamField>

<ParamField body="sessionId" type="string" required>
  The short-lived session ID generated by your backend. See [Session Tokens](/sdks/liveness-sdk).
</ParamField>

<ParamField body="sandboxEnvironment" type="boolean" default="false">
  Set to `true` to run in sandbox mode using test data. Set to `false` for production.
</ParamField>

<ParamField body="onSuccess" type="function">
  Callback invoked when the user successfully completes the verification flow. Receives a result data object.
</ParamField>

<ParamField body="onError" type="function">
  Callback invoked when verification fails or an error occurs. Receives an error object.
</ParamField>

<ParamField body="onClose" type="function">
  Callback invoked when the user closes the SDK modal without completing the flow.
</ParamField>

## How results link back to your entity

The session ID you generate is tied to the verification result on Youverify's side. After the SDK flow completes, call your backend to retrieve the result using the Liveness History endpoint or by reading the entity record via the API. The session ID is the join key between the SDK-collected biometric data and your entity record.

<Note>
  Session IDs are short-lived (default TTL: 120 seconds, configurable between 30 and 600 seconds). Generate a fresh session ID for each verification attempt — do not cache or reuse them.
</Note>

<Warning>
  Never pass your API secret key to the Web SDK. Use only your public merchant key on the client side. Your secret key must remain on your server.
</Warning>