React Native Implementation

React Native Project Requirements

Before React Native SDK integration, ensure your environment meets these requirements:

Node.js: v18+
npm: v9+ (or yarn v1.22+)
React: v17+
React Native: v0.72+
TypeScript (optional, but recommended): v5+
Android: 7.1+ (API level 25+)
iOS: 12.0+

React Native Installation

For React Native Users:

The code snippet below installs the SDK alongside its compulsory peer dependencies required to work seamlessly:

npm install kora-liveness-check-rn-sdk react-native-svg react-native-webview react-native-screens

yarn add kora-liveness-check-rn-sdk react-native-svg react-native-webview react-native-screens

Next step is to install the native pods for iOS setup (This is required):

cd ios
pod install
cd ..

Rebuild your App:

npx react-native run-android 
npx react-native run-ios

For Expo Users

The code snippet below installs the SDK:

npm install kora-liveness-check-rn-sdk

yarn add kora-liveness-check-rn-sdk

These peer dependencies must be installed for the SDK to function properly. The code snippet below automatically selects the versions compatible with your Expo SDK version:

npx expo install react-native-svg react-native-webview react-native-screens

Rebuild your App

For Android:

npx expo prebuild --clean
npx expo run:android

For iOS:

npx expo prebuild --clean
npx expo run:ios

📘
NOTE: We recommend always fetching the latest stable version from npm.

React Native Initialization & Configuration

The Kora Liveness Check React Native SDK offers both direct function calls and hook-based approaches for integration.

Basic Import:

import { koraLivenessService } from 'kora-liveness-check-rn-sdk';
import type { LivenessResult, LivenessConfig } from 'kora-liveness-check-rn-sdk';

Hook-based Approach (Recommended):

import { useLivenessCheck } from 'kora-liveness-check-rn-sdk';

const { startLivenessCheck, isLoading, result } = useLivenessCheck();

Universal Configuration Schema

The liveness verification service across all platforms uses a consistent configuration object schema:Note: The following schema represents the universal configuration format. Platform-specific implementations may have slight variations in method names or import paths, but the core configuration structure remains consistent across React Native, Web, and Flutter.

{
  publicKey: string;                              // Your merchant API public key
  type?: 'active' | 'passive';                   // Liveness type (optional for auto-detection)
  debugMode?: boolean;                           // Enable debug logging
  sandboxEnvironment?: boolean;                  // Use sandbox environment
  
  user: {                                        // User information (required)
    firstName: string;
    lastName?: string;
email?: string;
  };
  
  branding?: {                                   // UI customization (optional)
    name?: string;
    color?: string;                              // Primary brand color (hex)
    logo?: string;                               // Logo URL
    logoAlt?: string;
    hideLogoOnMobile?: boolean;
    showPoweredBy?: boolean;
    poweredByText?: string;
    poweredByLogo?: string;
  };
  
  presentation?: 'modal' | 'page';               // Presentation mode
  allowAudio?: boolean;                          // Allow audio instructions
  
  tasks?: Array<{                                // Custom tasks for active liveness
    id: string;                                  // Task identifier
    difficulty?: 'easy' | 'medium' | 'hard';
    timeout?: number;                            // Task timeout in milliseconds
    maxBlinks?: number;                          // For blink tasks
    maxNods?: number;                            // For motion tasks
    questions?: Array<{                          // For yes/no tasks
      question: string;
      answer: boolean;
     errorMessage?: string;
    }>;
  }>;
  
  // Callback functions
  onSuccess?: (result: LivenessResult) => void;
  onFailure?: (result: LivenessResult) => void;
  onClose?: () => void;
  onStart?: () => void;
}

Parameter Definitions

publicKey: (Required) Your merchant account's API public key
type: (Optional) Specify 'active' or 'passive' liveness check:
- Active Liveness: User performs prompted actions (blink, turn head, say phrases). Best for higher-assurance checks where interaction is acceptable
- Passive Liveness: System detects signs of life from natural video/image streams. Best for frictionless, low-to-medium risk flows. If omitted, the backend will auto-determine the best type based on risk assessment
user: (Required) Customer information including first name (required), last name, and email
branding: (Optional) Customize the UI with your brand colors, logos, and text
presentation:(Optional) Choose between 'modal' (overlay) or 'page' (full screen) presentation
tasks: (Optional) For active liveness, specify custom tasks like blink, motion detection, or yes/no questions
allowAudio: (Optional) Enable audio instructions during verification
onSuccess: (Optional) Callback function executed when verification succeeds
onFailure: (Optional) Callback function executed when verification fails
onClose:(Optional) Callback function executed when user closes the verification

React Native Integration Workflow

This section outlines the steps to integrate with our SDK.

Step 1: SDK Import and Setup.

Import the necessary components from the SDK:

import React, { useState } from 'react';
import { koraLivenessService } from 'kora-liveness-check-rn-sdk';
import type { LivenessResult } from 'kora-liveness-check-rn-sdk';

Step 2: Collect Verification Details

Prepare the configuration object with user details and verification settings:

const verificationConfig = {
  publicKey: 'your_public_key_here',
  debugMode: true,
  sandboxEnvironment: true,
  
  user: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]'
  },
  
  branding: {
    color: '#2376F3',
    logo: 'https://your-domain.com/logo.png',
    name: 'Your Company'
  },
  
  presentation: 'modal',
  allowAudio: false
};

Step 3: Start Verification Flow

Option A: Auto-Determined Type (Recommended)

Let the backend determine the best verification type:

const startAutoVerification = async () => {
  try {
    const component = await koraLivenessService.checkLiveness({
      ...verificationConfig,
      // No type specified - backend auto-determines based on risk
      onSuccess: (result: LivenessResult) => {
        console.log('Verification successful:', result);
        // Handle success - user verified as live human
      },
      onFailure: (result: LivenessResult) => {
        console.log('Verification failed:', result);
        // Handle failure - verification did not pass
      },
      onClose: () => {
        console.log('User closed verification');
        // Handle user cancellation
      }
    });
    
    // Render the component in your UI
    setLivenessComponent(component);
  } catch (error) {
    console.error('Failed to start verification:', error);
  }
};

Option B: Specific Verification Types

For specific verification types:

// Passive Liveness (Frictionless, good for low-risk flows)
const startPassiveVerification = async () => {
  const component = await koraLivenessService.checkLiveness({
    ...verificationConfig,
    type: 'passive',
    // ...callbacks
  });
};

// Active Liveness (Interactive, good for high-assurance flows)
const startActiveVerification = async () => {
  const component = await koraLivenessService.checkLiveness({
    ...verificationConfig,
    type: 'active',
    tasks: [
      {
        id: 'complete_the_circle',
        difficulty: 'medium',
        timeout: 30000
      },
      {
        id: 'blink',
        difficulty: 'easy',
        maxBlinks: 3,
        timeout: 15000
      }
    ],
    // ...callbacks
  });
};

Step 4: Handle the Verification Component

Render the verification component in your React Native application:

const App = () => {
  const [livenessComponent, setLivenessComponent] = useState(null);
  const [result, setResult] = useState(null);
  
  const handleVerification = async () => {
    try {
				const component = await koraLivenessService.checkLiveness({
        publicKey: 'your_public_key',
        user: {
          firstName: 'John',
          lastName: 'Doe',
          email: '[email protected]'
        },
        onSuccess: (result) => {
          setResult(result);
          setLivenessComponent(null);
        },
        onFailure: (result) => {
          setResult(result);
          setLivenessComponent(null);
        },
        onClose: () => {
          setLivenessComponent(null);
        }
      });
      
      setLivenessComponent(component);
    } catch (error) {
      console.error('Verification error:', error);
    }
  };
  
  if (livenessComponent) {
    return (
      <View style={{ flex: 1 }}>
        {livenessComponent}
      </View>
    );
  }
  
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <TouchableOpacity onPress={handleVerification}>
        <Text>Start Verification</Text>
      </TouchableOpacity>
      
      {result && (
        <Text>
          {result.success ? 'Verification Successful!' : 'Verification Failed'}
        </Text>
      )}
    </View>
  );
};

React Native Advanced Configuration

Custom Task Configuration for Active Liveness:

const customTasks = [
  {
    id: 'yes_or_no',
    difficulty: 'medium',
    questions: [
      {
        question: 'Are you ready to proceed?',
        answer: true,
        errorMessage: 'Please nod your head to the right for yes'
      }
    ]
  },
  {
    id: 'motions',
  	difficulty: 'hard',
    maxNods: 3,
    maxBlinks: 2,
    timeout: 45000
  }
];