Web Implementation

Web Installation & Setup

The Web SDK provides direct browser integration without requiring webview components.

Installation:

npm install @kora/liveness-check-web-sdk

Basic Import and Usage:

import { koraLivenessService, checkLiveness } from '@kora/liveness-check-web-sdk';
import type { LivenessConfig, LivenessOptions } from '@kora/liveness-check-web-sdk';

Web Integration Workflow

Step 1: Basic Setup

Option 1: Using the checkLiveness function (recommended)

const startWebVerification = async () => {
  try {
    await checkLiveness({
      publicKey: 'your_public_key',
      user: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]'
      },
      onSuccess: (result) => {
        console.log('Web verification successful:', result);
      },
      onFailure: (result) => {
        console.log('Web verification failed:', result);
      },
      onClose: () => {
        console.log('Web verification closed');
      }
    });
  } catch (error) {
    console.error('Web verification error:', error);
  }
};
// Option 2: Using the koraLivenessService instance
const startWebVerificationAlt = async () => {
  try {
    await koraLivenessService.checkLiveness({
      publicKey: 'your_public_key',
      user: {
        firstName: 'John',
        lastName: 'Doe',
        email: '[email protected]'
      },
      onSuccess: (result) => {
        console.log('Web verification successful:', result);
      },
      onFailure: (result) => {
        console.log('Web verification failed:', result);
      },
      onClose: () => {
        console.log('Web verification closed');
      }
    });
  } catch (error) {
    console.error('Web verification error:', error);
  }
};

LivenessOptions Configuration Interface:

{
  publicKey?: string;
  type?: 'active' | 'passive';                // Optional - defaults to 'active' if omitted
  debugMode?: boolean;
  sandboxEnvironment?: boolean;
  user?: {
    firstName?: string;
    lastName?: string;
    email?: string;
  };
  branding?: {
    name?: string;
    color?: string;
    logo?: string;
    logoAlt?: string;
    hideLogoOnMobile?: boolean;
    showPoweredBy?: boolean;
    poweredByText?: string;
    poweredByLogo?: string;
};
  presentation?: "modal" | "page";
  allowAudio?: boolean;
  tasks?: Array<{
    id: string;
    difficulty?: 'easy' | 'medium' | 'hard';
    timeout?: number;
    maxBlinks?: number;
    maxNods?: number;
    questions?: Array<{
      question: string;
      answer: boolean;
      errorMessage?: string;
    }>;
  }>;
  onSuccess?: (result: any) => void;
  onFailure?: (result: any) => void;
  onClose?: () => void;
}

Step 2: Full Example Implementation

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Kora Liveness Check</title>
</head>
<body>
    <div id="app">
        <button id="start-verification">Start Liveness Check</button>
        <div id="result"></div>
    </div>
<script type="module">
        import { checkLiveness } from '@kora/liveness-check-web-sdk';

        document.getElementById('start-verification').addEventListener('click', async () => {
            const resultDiv = document.getElementById('result');
            
            try {
                await checkLiveness({
                    publicKey: 'your_public_key_here',
                    user: {
                        firstName: 'John',
                        lastName: 'Doe',
                        email: '[email protected]'
                    },
                    debugMode: true,
                    sandboxEnvironment: true,
                    branding: {
                        color: '#2376F3',
                        logo: 'https://your-domain.com/logo.png',
                        name: 'Your Company'
                    },
                    presentation: 'modal',
                    onSuccess: (result) => {
                        resultDiv.innerHTML = '<p style="color: green;">Verification 													Successful!</p>';
                        console.log('Success:', result);
                    },
                    onFailure: (result) => {
                        resultDiv.innerHTML = '<p style="color: red;">Verification Failed!										</p>';
                        console.log('Failure:', result);
                    },
										onClose: () => {
                        console.log('User closed verification');
                    }
                });
            } catch (error) {
                console.error('Error starting verification:', error);
                resultDiv.innerHTML = '<p style="color: red;">Error starting 													verification</p>';
            }
        });
    </script>
</body>
</html>

Step 3: Advanced Configuration Options

// Default behavior (active liveness)
const defaultConfig = {
    publicKey: 'your_public_key',
    user: { firstName: 'John', email: '[email protected]' },
    // No type specified - defaults to 'active' liveness
};

// Explicitly active liveness (interactive)
const activeConfig = {
    publicKey: 'your_public_key',
    user: { firstName: 'John', email: '[email protected]' },
    type: 'active',
    allowAudio: true,
    tasks: [
        {
            id: 'complete-the-circle',
            difficulty: 'medium'
        },
{
            id: 'blink',
            difficulty: 'easy',
            maxBlinks: 3,
            timeout: 15000
        }
    ]
};

// Passive liveness (frictionless)
const passiveConfig = {
    publicKey: 'your_public_key',
    user: { firstName: 'John', email: '[email protected]' },
    type: 'passive',
    presentation: 'page'
};

// Available task IDs for active liveness:
// - 'complete-the-circle'
// - 'blink'
// - 'motions'
// - 'yes-or-no'

// Usage examples
await checkLiveness(defaultConfig);        // Uses active liveness by default
await checkLiveness(activeConfig);        // Explicit active liveness
await checkLiveness(passiveConfig);       // Passive liveness

Step 4: Service Initialization (Advanced Usage)

// Option 1: Auto-initialization (recommended)
// The checkLiveness function automatically initializes the service with your publicKey
// Option 2: Manual initialization
import { koraLivenessService } from '@kora/liveness-check-web-sdk';

await koraLivenessService.initialize({
    publicKey: 'your_public_key',
    livenessOptions: {
        debugMode: true,
        sandboxEnvironment: true
    }
});

// Then use the service
await koraLivenessService.checkLiveness({
    user: { firstName: 'John', email: '[email protected]' },
    type: 'active'
});

// Option 3: Reset service state
koraLivenessService.reset();

Default Configuration Values (from SDK):

{
  "user": {
    "firstName": "User",
    "lastName": "Test"
  },
  "branding": {
    "color": "#2376F3",
    "logo": "",
    "name": "Kora"
  },
  "presentation": "modal",
  "sandboxEnvironment": true,
  "allowAudio": false
}

Browser Requirements:

Modern browsers with WebRTC support (Chrome 60+, Firefox 55+, Safari 11+, Edge 79+)
HTTPS required for camera access (except localhost for development)
Camera permissions granted by user.

Common Web-Specific Issues

Camera permissions: Ensure your site is served over HTTPS
Network connectivity: Verify internet connection for API communication
Cross-browser compatibility: Test across different browsers
API configuration: Verify publicKey and user.firstName are provided (firstName is required)
Type behavior: If no type is specified, SDK defaults to 'active' liveness

Troubleshooting

Check browser console for any JavaScript errors
Ensure camera permissions are granted
Verify API key is correct for the environment (sandbox vs production)
Ensure user.firstName is provided (required field)
Test with different browsers if issues persist