🎯 Kora Liveness Check Web SDK

Add secure liveness verification to your web application in minutes!

The Kora Liveness SDK provides comprehensive facial liveness detection to prevent fraud and ensure real users during identity verification. Perfect for KYC compliance, onboarding flows, and secure authentication.

✨ Why Choose Kora Liveness SDK?

• 🚀 Quick Integration - Add liveness verification in under 10 minutes
• 🛡️ Fraud Prevention - Advanced anti-spoofing technology
• 🎨 White-Label Ready - Full customization with your branding
• 📱 Mobile Optimized - Works seamlessly on all devices
• 🔧 Developer Friendly - Simple API with comprehensive documentation
• ⚡ High Performance - Lightweight and fast verification
• 🌍 Global Scale - Enterprise-grade reliability

🚀 Quick Start Guide

1. Install the SDK

npm install kora-identity-web-sdk

2. Start Verification (Auto-Initialize)

import { koraLivenessService } from 'kora-identity-web-sdk'

// One-step liveness verification with auto-initialization
await koraLivenessService.checkLiveness({
  // SDK Configuration (auto-initializes)
  publicKey: 'your-public-key',
  debugMode: false,
  
  // Liveness Type (optional - auto-determined if not specified)
  type: 'active', // 'active' | 'passive' | undefined (auto-determine)
  
  // User & Verification Configuration
  user: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]'
  },
  branding: {
    color: '#your-brand-color',    // Customizable: Your brand color
    logo: 'https://yoursite.com/logo.png'  // Customizable: Your logo URL
    // Note: name, poweredByText, and other properties are controlled by Kora
  },
  tasks: [{ 
    id: 'complete-the-circle',
    difficulty: 'medium'
  }],
  onSuccess: (result) => {
    console.log('✅ Verification passed!', result)
    // Redirect user or update UI
  },
  onFailure: (error) => {
    console.log('❌ Verification failed', error)
    // Handle failure (retry, fallback, etc.)
  }
})

🎯 Auto-Determination Feature: When you don't specify a type, the SDK defaults to active liveness verification.

That's it! Your users can now complete liveness verification with just a few clicks.

🎯 Verification Types

🚀 Auto-Determination (Recommended)

Let the SDK automatically choose the best verification method:

await koraLivenessService.checkLiveness({
  // No 'type' specified - SDK intelligently selects optimal method
  user: { firstName: 'John', lastName: 'Doe' },
  onSuccess: (result) => console.log('Verified with:', result.verificationType)
})

When no type is specified, the SDK defaults to active liveness verification, which provides interactive verification with specific user actions.

Active Liveness Verification

Interactive verification where users perform specific actions:

• Complete the Circle - User follows a circle with head movement
• Yes or No Questions - User answers by tilting head (right=yes, left=no)
• Motion Commands - User performs nodding, blinking, or mouth opening
• Blink Test - User blinks a specified number of times

Passive Liveness Verification

Automatic verification requiring no user interaction:

• Silent Detection - User simply looks at camera
• Anti-Spoofing - Advanced checks for photos, videos, masks
• Face Analysis - Depth perception and micro-movement detection

🔧 Configuration Options

Basic Configuration

const config = {
  user: {
    firstName: 'John',           // Required
    lastName: 'Doe',             // Optional  
    email: '[email protected]'    // Optional
  },
  
  // Customize verification tasks
  tasks: [{ 
    id: 'complete-the-circle',   // Task type
    difficulty: 'medium',        // easy, medium, hard
    timeout: 30000              // 30 seconds
  }],
  
  // Your brand styling (limited customization)
  branding: {
    color: '#2376F3',           // Customizable: Primary brand color
    logo: 'https://yoursite.com/logo.png'  // Customizable: Your logo URL
    // Note: Company name and other branding elements are controlled by Kora
  },
  
  // Display options
  presentation: 'modal',        // 'modal' or 'page'
  allowAudio: true,            // Voice instructions
  
  // Event handlers
  onSuccess: (result) => { /* Handle success */ },
  onFailure: (error) => { /* Handle failure */ },
  onClose: () => { /* Handle modal close */ }
}

💼 Implementation Examples

E-commerce Account Verification

// During user registration or high-value transactions
await koraLivenessService.checkLiveness({
  type: 'active', // Or omit for auto-determination
  user: {
    firstName: userForm.firstName,
    lastName: userForm.lastName, 
    email: userForm.email
  },
  tasks: [{ id: 'complete-the-circle', difficulty: 'easy' }],
  branding: {
    color: '#FF6B35' // Your brand color (logo property also available)
  },
  onSuccess: (result) => {
    // Mark account as verified
    updateUserStatus('verified');
    redirectTo('/dashboard');
  },
  onFailure: () => {
    showMessage('Verification failed. Please try again.');
  }
})

Banking KYC Compliance

// For regulatory compliance and fraud prevention
await koraLivenessService.checkLiveness({
  type: 'active', // Explicit type for compliance requirements
  user: { 
    firstName: customer.firstName,
    lastName: customer.lastName
  },
  tasks: [
    { id: 'motions', difficulty: 'medium', maxBlinks: 3, maxNods: 2 },
    { id: 'complete-the-circle', timeout: 45000 }
  ],
  branding: {
    color: '#1E3A8A',
    logo: '/bank-logo.png'
  },
  onSuccess: (result) => {
    // Submit to compliance system
    submitKYCVerification(customer.id, result);
    proceedWithAccountOpening();
  }
})

Healthcare Patient Verification

// Secure patient identity verification for telehealth
await koraLivenessService.checkLiveness({
  type: 'passive', // Passive for easier user experience
  user: {
    firstName: patient.firstName,
    lastName: patient.lastName
  },
  branding: {
    color: '#059669'
  },
  presentation: 'page', // Full page for better UX
  onSuccess: (result) => {
    startTelemedicineSession(patient.id, result);
  }
})

SaaS Application Security

// Add extra security for sensitive operations
async function performSensitiveAction() {
  await koraLivenessService.checkLiveness({
    // No type specified - let SDK auto-determine best method
    user: currentUser,
    tasks: [{ id: 'blink', maxBlinks: 2, timeout: 20000 }],
    branding: yourAppBranding,
    onSuccess: () => {
      // Proceed with sensitive operation
      deleteAllUserData();
    },
    onFailure: () => {
      logSecurityEvent('Failed liveness check for sensitive operation');
    }
  })
}

🔧 Setup & Integration

1. Get Your API Keys

Contact the Kora team to get your API credentials:

• Public Key - For client-side SDK initialization
• Documentation - Integration guides and best practices

🔧 Advanced Integration

1. Manual Initialization (Optional)

For applications that need fine-grained control, you can manually initialize the SDK before use:

// Manual initialization for advanced use cases
await koraLivenessService.initialize({
  publicKey: 'your-public-key',
  livenessOptions: {
    debugMode: false,
    provider: 'youverify' // Future: specify different providers
  }
})

// Then use without SDK config in the call
await koraLivenessService.checkLiveness({
  type: 'active', // Optional - can be omitted for auto-determination
  user: { firstName: 'John', lastName: 'Doe' },
  // No publicKey needed here - already initialized
  onSuccess: (result) => console.log('Success:', result)
})

2. Environment Setup

Sandbox (Development):

await koraLivenessService.initialize({
  publicKey: 'pk_test_your_sandbox_key',
  livenessOptions: { debugMode: true }
})

Production:

await koraLivenessService.initialize({
  publicKey: 'pk_live_your_production_key',
  livenessOptions: { debugMode: false }
})

3. HTML Integration (No Build Tools)

<!DOCTYPE html>
<html>
<head>
  <title>Liveness Verification</title>
</head>
<body>
  <button id="verify-btn">Verify Identity</button>
  
  <script type="module">
    import { koraLivenessService } from 'https://unpkg.com/kora-identity-web-sdk/dist/index.esm.js'
    
    document.getElementById('verify-btn').onclick = async () => {
      // Auto-initialization - no separate initialize() call needed
      await koraLivenessService.checkLiveness({
        publicKey: 'your-public-key',
        type: 'active', // Optional - omit for auto-determination
        user: { firstName: 'John', lastName: 'Doe' },
        onSuccess: (result) => alert('Verified!'),
        onFailure: (error) => alert('Failed!')
      })
    }
  </script>
</body>
</html>

🌐 Environment Detection & Base URL Override

✨ Automatic Environment Detection

The SDK automatically detects the environment from your public key prefix - no manual configuration needed!

// ✅ AUTOMATIC DETECTION (Recommended)
await koraLivenessService.checkLiveness({
  publicKey: 'pk_test_sandbox_key',  // 🎯 Auto-detects sandbox environment
  // publicKey: 'pk_live_production_key',  // 🎯 Auto-detects live environment
  user: { firstName: 'John', lastName: 'Doe' },
  onSuccess: (result) => console.log('Success!', result)
})

// Check detected environment
const envInfo = koraLivenessService.getEnvironmentInfo()
console.log(envInfo)
// Output:
// {
//   detected: { isSandbox: true, source: 'publicKey' },
//   confirmed: { isSandbox: true, isLive: false }  // After backend response
// }

🔧 Environment Detection Rules

| Public Key Prefix | Environment | API Endpoint | |------------------|-------------|--------------| | pk_test_* | Sandbox | Automatic detection | | pk_live_* | Live | Automatic detection |

🎯 Backend Confirmation

The SDK performs dual-layer environment detection:

1. Immediate Detection: From public key prefix (pk_test_* / pk_live_*)
2. Backend Confirmation: From API response is_live field (authoritative)

// Environment is updated automatically from backend responses
await koraLivenessService.checkLiveness({
  publicKey: 'pk_test_development_key',
  user: { firstName: 'Test', lastName: 'User' },
  onSuccess: (result) => {
    // Environment confirmed by backend at this point
    const env = koraLivenessService.getEnvironmentInfo()
    console.log('Confirmed Environment:', env.confirmed)
    // Output: { isSandbox: true, isLive: false }
  }
})

🔧 API Base URL Override (For Internal Testing)

Override the API endpoint for internal development and testing:

// Production Default (NPM packages)
await koraLivenessService.checkLiveness({
  publicKey: 'pk_live_production_key',
  // Uses default production URL: https://api.korapay.com
  user: { firstName: 'Production', lastName: 'User' }
})

// Internal Testing Override
await koraLivenessService.checkLiveness({
  publicKey: 'pk_test_development_key',
  apiBaseUrl: 'https://api.koraapi.com',  // 🎯 Override to staging
  user: { firstName: 'Dev', lastName: 'User' }
})

// Manual Initialization with URL Override
await koraLivenessService.initialize({
  publicKey: 'pk_test_staging_key',
  apiBaseUrl: 'https://staging-api.example.com',  // Custom endpoint
  livenessOptions: { debugMode: true }
})

📋 Migration Guide (Breaking Changes)

If you're upgrading from a previous version:

// ❌ OLD WAY (No longer supported)
await koraLivenessService.checkLiveness({
  publicKey: 'pk_test_xyz',
  sandboxEnvironment: true,  // ❌ Manual setting removed
  user: { firstName: 'User' }
})

// ✅ NEW WAY (Automatic detection)
await koraLivenessService.checkLiveness({
  publicKey: 'pk_test_xyz',  // ✅ Automatically detects sandbox
  // apiBaseUrl: 'https://api.koraapi.com',  // 🔧 Optional for internal testing
  user: { firstName: 'User' }
})

✅ Benefits Summary

• 🚀 Simplified API: No manual environment configuration
• 🎯 Accurate Detection: Backend confirmation overrides client detection
• 🔧 Flexible Testing: Easy URL override for internal development
• 📦 NPM Ready: Production URLs by default, no environment variables needed
• 🛡️ Conflict Prevention: No manual/automatic environment mismatches
• 📊 Full Visibility: Track both detected and confirmed states

4. React Integration

import { koraLivenessService } from 'kora-identity-web-sdk'
import { useState, useEffect } from 'react'

function IdentityVerification() {
  const [isVerifying, setIsVerifying] = useState(false)
  const [isVerified, setIsVerified] = useState(false)

  useEffect(() => {
    // Initialize SDK on component mount
    koraLivenessService.initialize({
      publicKey: process.env.REACT_APP_KORA_PUBLIC_KEY
    })
  }, [])

  const startVerification = async (livenessType = undefined) => {
    setIsVerifying(true)
    
    try {
      await koraLivenessService.checkLiveness({
        type: livenessType, // undefined = auto-determine, 'active' or 'passive' for explicit
        user: {
          firstName: user.firstName,
          lastName: user.lastName,
          email: user.email
        },
        branding: {
          color: '#your-brand-color'
          // logo: 'https://yoursite.com/logo.png' // Optional
        },
        tasks: livenessType === 'active' ? [{ id: 'complete-the-circle', difficulty: 'medium' }] : undefined,
        onSuccess: (result) => {
          setIsVerified(true)
          setIsVerifying(false)
          // Handle success
        },
        onFailure: (error) => {
          setIsVerifying(false)
          // Handle failure  
        }
      })
    } catch (error) {
      setIsVerifying(false)
      console.error('Verification failed to start:', error)
    }
  }

  return (
    <div>
      {!isVerified ? (
        <div>
          <button 
            onClick={() => startVerification('active')}
            disabled={isVerifying}
            style={{ marginRight: '10px' }}
          >
            {isVerifying ? 'Verifying...' : 'Active Verification'}
          </button>
          <button 
            onClick={() => startVerification('passive')}
            disabled={isVerifying}
            style={{ marginRight: '10px' }}
          >
            {isVerifying ? 'Verifying...' : 'Passive Verification'}
          </button>
          <button 
            onClick={() => startVerification()} // No type = auto-determine
            disabled={isVerifying}
          >
            {isVerifying ? 'Verifying...' : 'Auto-Determine'}
          </button>
        </div>
      ) : (
        <p>✅ Identity Verified Successfully!</p>
      )}
    </div>
  )
}

📖 API Reference

Core Methods

initialize(config)

Initialize the SDK with your credentials.

await koraLivenessService.initialize({
  publicKey: 'your-public-key',     // Required: Your API public key
  livenessOptions: {                // Optional: SDK configuration
    debugMode: false                // Enable console logging
  }
})

checkLiveness(config)

NEW UNIFIED API - Start liveness verification with a single method.

await koraLivenessService.checkLiveness({
  type: 'active',                   // Optional: 'active' | 'passive' | undefined (auto-determine)
  user: {
    firstName: 'string',            // Required: User's first name
    lastName: 'string',             // Optional: User's last name  
    email: 'string'                 // Optional: User's email
  },
  tasks: [{                         // Optional: Verification tasks (for active liveness)
    id: 'complete-the-circle',      // Task type (see task options)
    difficulty: 'medium',           // easy, medium, hard
    timeout: 30000,                 // Milliseconds
    maxBlinks: 5                    // For blink tasks
  }],
  branding: {                       // Optional: Limited custom branding
    color: '#2376F3',               // Primary color (hex) - customizable
    logo: 'https://logo-url.png'    // Logo URL - customizable
    // Note: name, poweredByText, showPoweredBy are controlled by Kora
  },
  presentation: 'modal',            // 'modal' or 'page'
  allowAudio: true,                 // Voice instructions
  onSuccess: (result) => {},        // Success callback
  onFailure: (error) => {},         // Failure callback  
  onClose: () => {}                 // Modal close callback
})

// Auto-determination (recommended for best UX)
await koraLivenessService.checkLiveness({
  // No 'type' specified - defaults to active liveness
  user: { firstName: 'John', lastName: 'Doe' },
  branding: { color: '#2376F3' },
  onSuccess: (result) => { /* Handle success */ },
  onFailure: (error) => { /* Handle failure */ }
})

// Explicit passive liveness
await koraLivenessService.checkLiveness({
  type: 'passive',
  user: { firstName: 'John', lastName: 'Doe' },
  branding: { color: '#2376F3', name: 'Your App' },
  onSuccess: (result) => { /* Handle success */ },
  onFailure: (error) => { /* Handle failure */ }
})

Parameters:

• config: Configuration object with optional type, user data, branding, and callbacks

Direct Methods

// Direct methods for specific liveness types
await koraLivenessService.startActiveLiveness(config)   // Direct active liveness
await koraLivenessService.startPassiveLiveness(config)  // Direct passive liveness

// Recommended: Use unified checkLiveness method
await koraLivenessService.checkLiveness({ type: 'active', ...config })

Task Options

| Task ID | Description | Options | |---------|-------------|---------| | complete-the-circle | Follow circle with head movement | difficulty, timeout | | yes-or-no | Answer questions by tilting head | difficulty, timeout, questions | | motions | Perform nodding, blinking, mouth opening | difficulty, timeout, maxNods, maxBlinks | | blink | Blink specified number of times | difficulty, timeout, maxBlinks |

Utility Methods

isConfigured()

Check if SDK is properly initialized.

getCurrentSession()

Get current session information for debugging.

clearSession()

Clear current session data.

getDebugInfo()

Get detailed SDK state information.

🔍 Testing & Debugging

Test Your Integration

The SDK includes a comprehensive test interface for development:

# Install the SDK
npm install kora-identity-web-sdk

# Run test interface
npm run test-dev

This opens http://localhost:8000/test.html with:

• ✅ Live SDK Testing - Test all verification types
• ⚙️ Configuration UI - Adjust settings visually
• 🎨 Branding Preview - See your customizations
• 📊 Debug Console - Real-time logging and state inspection
• 📱 Responsive Testing - Mobile and desktop views

Debugging Tips

Check SDK Status:

console.log('Is configured:', koraLivenessService.isConfigured())
console.log('Session info:', koraLivenessService.getCurrentSession())
console.log('Debug info:', koraLivenessService.getDebugInfo())

Common Issues & Solutions:

| Issue | Solution | |-------|----------| | "SDK not initialized" | Call initialize() with valid credentials first | | "Public key required" | Ensure your public key is not empty/undefined | | Modal doesn't appear | Check for JavaScript errors in console | | Verification fails immediately | Verify your API key is correct and valid | | Camera permission denied | Guide users to enable camera access |

Enable Debug Mode:

await koraLivenessService.initialize({
  publicKey: 'your-key',
  livenessOptions: { debugMode: true } // Enables detailed logging
})

🚀 Going Live

Pre-Launch Checklist

• ✅ Test all verification types in your staging environment
• ✅ Verify branding looks correct on mobile and desktop
• ✅ Test error handling for failed verifications
• ✅ Check camera permissions flow for new users
• ✅ Validate backend integration and webhook handling
• ✅ Performance test with expected user load
• ✅ Security review of API key management

Production Deployment

// Production configuration
await koraLivenessService.initialize({
  publicKey: 'pk_live_your_production_key',     // Live API key
  livenessOptions: { 
    debugMode: false                            // Disable debug logs
  }
})

Monitoring & Analytics

Track verification success rates and user experience:

await koraLivenessService.checkLiveness({
  type: 'active', // Or omit for auto-determination
  // ... your config
  onSuccess: (result) => {
    // Track successful verification
    analytics.track('liveness_verification_success', {
      task_type: result.taskType,
      duration: result.duration,
      user_id: currentUser.id
    })
  },
  onFailure: (error) => {
    // Track failed verification  
    analytics.track('liveness_verification_failed', {
      error_type: error.type,
      retry_count: error.retryCount
    })
  }
})

⚠️ Error Handling & Edge Cases

Comprehensive Error Handling

async function performLivenessCheck() {
  try {
    await koraLivenessService.checkLiveness({
      type: 'active', // Or omit for auto-determination
      user: { firstName: 'John', lastName: 'Doe' },
      onSuccess: (result) => {
        // Verification passed - proceed with user flow
        handleSuccessfulVerification(result)
      },
      onFailure: (error) => {
        // Verification failed - handle gracefully
        handleFailedVerification(error)
      },
      onClose: () => {
        // User closed modal - track abandonment
        trackVerificationAbandoned()
      }
    })
  } catch (initError) {
    // SDK initialization failed
    console.error('Failed to initialize liveness check:', initError)
    showFallbackVerificationMethod()
  }
}

function handleFailedVerification(error) {
  switch (error.type) {
    case 'CAMERA_ACCESS_DENIED':
      showMessage('Please enable camera access and try again')
      break
    case 'POOR_LIGHTING':
      showMessage('Please move to a well-lit area')
      break  
    case 'MULTIPLE_FACES':
      showMessage('Please ensure only one person is visible')
      break
    case 'NETWORK_ERROR':
      showMessage('Connection issue. Please check internet and retry')
      break
    default:
      showMessage('Verification failed. Please try again')
  }
}

User Experience Best Practices

Camera Permissions:

// Check camera permissions before starting
if (!await checkCameraPermissions()) {
  showCameraPermissionInstructions()
  return
}

await koraLivenessService.startActiveLiveness(config)

Loading States:

// Show loading indicator
setLoading(true)
setMessage('Preparing liveness verification...')

try {
  await koraLivenessService.initialize(config)
  setMessage('Ready! Please follow the on-screen instructions.')
  
  await koraLivenessService.checkLiveness({
    type: 'active', // Or omit for auto-determination
    // config
  })
} finally {
  setLoading(false)
}

Retry Logic:

let retryCount = 0
const MAX_RETRIES = 3

async function attemptVerification() {
  try {
    await koraLivenessService.checkLiveness({
      type: 'active', // Or omit for auto-determination
      // config
      onFailure: (error) => {
        if (retryCount < MAX_RETRIES && error.type !== 'FRAUD_DETECTED') {
          retryCount++
          setTimeout(attemptVerification, 2000) // Retry after 2 seconds
        } else {
          handleFinalFailure(error)
        }
      }
    })
  } catch (error) {
    handleFinalFailure(error)
  }
}

🔒 Security & Compliance

Security Best Practices

✅ Do:

• Store API keys securely as environment variables
• Validate verification results on your backend
• Implement rate limiting for verification requests
• Use HTTPS for all API communications
• Log verification attempts for audit trails
• Implement proper user consent flows

❌ Don't:

• Hardcode API keys in client-side code
• Trust client-side verification results alone
• Skip backend validation of liveness results
• Allow unlimited verification attempts
• Store sensitive user data unnecessarily

GDPR & Privacy Compliance

// Implement proper consent handling
const userConsent = await getUserConsent()
if (!userConsent.biometricProcessing) {
  showConsentRequired()
  return
}

await koraLivenessService.checkLiveness({
  type: 'active', // Or omit for auto-determination
  user: userData,
  onSuccess: (result) => {
    // Process result according to privacy policy
    processVerificationResult(result, userConsent)
  }
})

Data Retention

The SDK automatically handles secure data transmission. Implement your own data retention policies:

// Example: Auto-delete verification data after 30 days
const RETENTION_DAYS = 30
setTimeout(() => {
  deleteVerificationData(sessionId)
}, RETENTION_DAYS * 24 * 60 * 60 * 1000)

🌍 Browser & Device Support

| Browser | Version | Mobile | Desktop | |---------|---------|--------|---------| | Chrome | 88+ | ✅ | ✅ |
| Safari | 14+ | ✅ | ✅ | | Firefox | 85+ | ✅ | ✅ | | Edge | 88+ | ✅ | ✅ |

Requirements:

• Camera access capability
• JavaScript enabled
• HTTPS connection (required for camera access)
• Minimum 1MB network connection

📞 Support & Resources

Get Help

• � Email Support: [email protected]
• 📖 Documentation: docs.korapay.com
• � Developer Chat: Join our Slack community
• 🐛 Report Issues: GitHub Issues

Additional Resources

• 🎥 Video Tutorials: Integration walkthroughs
• 🔧 Code Examples: Complete implementation samples
• � Best Practices: Security and UX guidelines
• � Changelog: Release Notes

Business Inquiries

• � Sales: [email protected]
• 🤝 Partnerships: [email protected]
• 📈 Enterprise: [email protected]

🎉 Ready to Get Started?

1. 📞 Contact Us - Get your API credentials
2. ⚡ Quick Integration - Use our 10-minute setup guide
3. 🧪 Test Thoroughly - Use our comprehensive test suite
4. 🚀 Go Live - Deploy with confidence

Start building secure, fraud-proof identity verification today!

Built with ❤️ by the Kora team. Securing digital identities worldwide.