@nina997/react-native-aws-face-liveness

React Native library for AWS Face Liveness detection with native Android implementation using AWS Rekognition.

Features

• 🎯 Face Liveness Detection using AWS Rekognition
• 📷 Native camera integration with CameraX
• 🔄 Head turn validation flow (center, left, right positions)
• 📊 Face mesh data extraction and S3 upload
• 📸 Image capture with base64 encoding
• 🎨 Visual feedback with face overlay and animations
• 🔒 Secure AWS Cognito Identity Pool authentication

Installation

npm install @nina997/react-native-aws-face-liveness
# or
yarn add @nina997/react-native-aws-face-liveness

Peer Dependencies

This library requires the following peer dependencies:

npm install @aws-sdk/client-rekognition @aws-sdk/client-s3 @aws-sdk/credential-providers
# or
yarn add @aws-sdk/client-rekognition @aws-sdk/client-s3 @aws-sdk/credential-providers

Android Setup

1. The library uses manual linking. Make sure your MainApplication.kt imports and registers the package:

import com.facedetection.AWSLivenessPackage

class MainApplication : Application(), ReactApplication {
  override val reactNativeHost: ReactNativeHost =
      object : DefaultReactNativeHost(this) {
        override fun getPackages(): List<ReactPackage> =
            PackageList(this).packages.apply {
              add(AWSLivenessPackage())
            }
      }
}

2. Ensure your android/app/build.gradle includes the dependency:

dependencies {
    implementation project(':react-native-face-detection')
}

3. The following permissions are required in your AndroidManifest.xml:

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

iOS Setup

iOS support is planned but not yet implemented.

Configuration

Before using the library, configure your AWS credentials in src/config/aws.ts:

export const awsRekognition = {
  region: 'us-east-1',
  identityPoolId: 'us-east-1:YOUR-IDENTITY-POOL-ID',
};

export const awsS3Config = {
  region: 'us-east-1',
  identityPoolId: 'us-east-1:YOUR-IDENTITY-POOL-ID',
  bucketName: 'your-bucket-name',
};

Required AWS Resources

1. Cognito Identity Pool: For unauthenticated access to Rekognition and S3
2. IAM Role: With permissions for:
   • rekognition:CreateFaceLivenessSession
   • rekognition:GetFaceLivenessSessionResults
   • rekognition:DetectFaces
   • s3:PutObject
3. S3 Bucket: For storing facemesh data and captured images

Usage

import { FaceDetection } from '@nina997/react-native-aws-face-liveness';

export default function App() {
  return <FaceDetection />;
}

The FaceDetection component provides a complete UI for:

• Initiating a liveness session
• Capturing face images with head turn validation
• Analyzing face liveness
• Displaying results with confidence scores

How It Works

1. Session Creation: Creates an AWS Rekognition Face Liveness session
2. Native Camera Flow: Launches native Android activity with camera
3. Head Turn Validation:
   • User centers their face
   • Turns head left
   • Turns head right
   • Returns to center for final capture
4. Face Analysis: Detects faces and validates liveness using AWS Rekognition
5. Data Upload: Uploads facemesh data and images to S3
6. Results: Returns confidence scores and session results

Development

Building the Library

After making changes to the source code, rebuild the library:

yarn prepare

This compiles TypeScript and generates the lib directory.

Running the Example App

cd example
yarn install
yarn android

Architecture

Android Native Components

• AWSLivenessModule: React Native bridge module
• AWSLivenessPackage: Package registration
• FaceLivenessActivity: Native camera activity with face detection
• FaceOverlayView: Custom view for visual feedback
• FaceDetectionPackage: Alternative package (legacy)

JavaScript/TypeScript

• FaceDetection.tsx: Main React component
• NativeFaceDetection.ts: Native module interface
• s3Upload.ts: S3 upload utilities
• aws.ts: AWS configuration

Troubleshooting

Build Issues

If you encounter build errors:

1. Clean and rebuild:

   cd example/android && ./gradlew clean && cd ../..
   yarn android

2. Ensure peer dependencies are installed in the root:

   yarn add --dev @aws-sdk/client-rekognition @aws-sdk/client-s3 @aws-sdk/credential-providers

3. Rebuild the library:

   yarn prepare

Module Resolution Errors

If Metro bundler can't find the module:

• Make sure lib directory exists (run yarn prepare)
• Restart Metro bundler
• Clear Metro cache: yarn start --reset-cache

Camera Permission Issues

Make sure to request camera permission at runtime before launching the face detection flow.

API Reference

FaceDetection Component

Main component that handles the complete face liveness detection flow.

Props: None (self-contained component)

Features:

• Session management
• Native camera integration
• Face liveness analysis
• Results display

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library