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:

Install the SDK

npm install kora-identity-react-native-sdk

yarn add kora-identity-react-native-sdk

For iOS, install pods

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-identity-react-native-sdk

yarn add kora-identity-react-native-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-webview

Rebuild your App

For Android:

npx expo prebuild --cleannpx expo run:android

For iOS:

npx expo prebuild --cleannpx expo run:ios

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

React Native Permissions

Android

Add camera permission to your Android manifest:

<uses-permission android:name="android.permission.CAMERA" />

If your app flow requires audio support, you may also need microphone permission depending on your setup.

iOS

Add camera usage description to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for liveness verification.</string>

If your app flow requires microphone access, add the appropriate microphone usage description as well.

React Native Import and Setup

import { koraLivenessService } from 'kora-identity-react-native-sdk';
import type {
  LivenessConfig,
  LivenessResult,
} from 'kora-identity-react-native-sdk';

You can also use the component wrapper:

import { LivenessCheck } from 'kora-identity-react-native-sdk';

React Native Configuration Example

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

React Native Start Verification

Auto or Platform-Determined Flow

const startVerification = async () => {
  try {
    const component = await koraLivenessService.checkLiveness({
      ...verificationConfig,
      onSuccess: (result: LivenessResult) => {
        console.log('Verification successful:', result);
      },
      onFailure: (result: LivenessResult) => {
        console.log('Verification failed:', result);
      },
      onClose: () => {
        console.log('User closed verification');
      },
    });

    setLivenessComponent(component);
  } catch (error) {
    console.error('Failed to start verification:', error);
  }
};

Explicit Passive Liveness

const startPassiveVerification = async () => {
  const component = await koraLivenessService.checkLiveness({
    ...verificationConfig,
    type: 'passive',
    onSuccess: (result: LivenessResult) => {
      console.log('Passive verification successful:', result);
    },
    onFailure: (result: LivenessResult) => {
      console.log('Passive verification failed:', result);
    },
    onClose: () => {
      console.log('Verification closed');
    },
  });

  setLivenessComponent(component);
};

Explicit Active Liveness

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,
      },
    ],
    onSuccess: (result: LivenessResult) => {
      console.log('Active verification successful:', result);
    },
    onFailure: (result: LivenessResult) => {
      console.log('Active verification failed:', result);
    },
    onClose: () => {
      console.log('Verification closed');
    },
  });

  setLivenessComponent(component);
};

React Native Render Example

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { koraLivenessService } from 'kora-identity-react-native-sdk';
import type { LivenessResult } from 'kora-identity-react-native-sdk';

const App = () => {
  const [livenessComponent, setLivenessComponent] =
    useState<React.ReactElement | null>(null);
  const [result, setResult] = useState<LivenessResult | null>(null);

  const handleVerification = async () => {
    try {
      const component = await koraLivenessService.checkLiveness({
        publicKey: 'your_public_key',
        user: {
          firstName: 'John',
          lastName: 'Doe',
          email: '[email protected]',
        },
        onSuccess: (response) => {
          setResult(response);
          setLivenessComponent(null);
        },
        onFailure: (response) => {
          setResult(response);
          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' }}>
      <Button title="Start Verification" onPress={handleVerification} />
    </View>
  );
};

export default App;

React Native Alternative Component Wrapper

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import { LivenessCheck } from 'kora-identity-react-native-sdk';

const App = () => {
  const [showLiveness, setShowLiveness] = useState(false);

  if (showLiveness) {
    return (
      <View style={{ flex: 1 }}>
        <LivenessCheck
          publicKey="your-kora-public-key"
          config={{
            user: {
              firstName: 'John',
              lastName: 'Doe',
              email: '[email protected]',
            },
            branding: {
              color: '#2376F3',
            },
          }}
          onSuccess={(result) => {
            console.log('Success:', result);
            setShowLiveness(false);
          }}
          onFailure={(result) => {
            console.log('Failed:', result);
            setShowLiveness(false);
          }}
          onClose={() => setShowLiveness(false)}
        />
      </View>
    );
  }

  return (
    <View style={{ flex: 1, justifyContent: 'center', padding: 20 }}>
      <Button
        title="Start Liveness Check"
        onPress={() => setShowLiveness(true)}
      />
    </View>
  );
};

export default App;

React Native Active Liveness Task Example

const customTasks = [
  {
    id: 'yes_or_no',
    difficulty: 'medium',
    questions: [
      {
        question: 'Are you ready to proceed?',
        answer: true,
        errorMessage: 'Please respond as instructed on screen',
      },
    ],
  },
  {
    id: 'motions',
    difficulty: 'hard',
    maxNods: 3,
    maxBlinks: 2,
    timeout: 45000,
  },
];

Universal Configuration Schema

The liveness verification service across all platforms uses a consistent configuration object schema:

📘
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;
  };
  
  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 the user closes the verification