npm package: @nina997/react-native-aws-face-liveness
Description: React Native library for AWS Face Liveness detection
Author: FaceDetection
Latest version: 0.1.2

# @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

```sh
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:

```sh
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:

```kotlin
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:

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

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

```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`:

```typescript
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

```tsx
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:

```sh
yarn prepare
```

This compiles TypeScript and generates the `lib` directory.

### Running the Example App

```sh
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:
   ```sh
   cd example/android && ./gradlew clean && cd ../..
   yarn android
   ```

2. Ensure peer dependencies are installed in the root:
   ```sh
   yarn add --dev @aws-sdk/client-rekognition @aws-sdk/client-s3 @aws-sdk/credential-providers
   ```

3. Rebuild the library:
   ```sh
   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](CONTRIBUTING.md#development-workflow)
- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
- [Code of conduct](CODE_OF_CONDUCT.md)

## License

MIT

---

Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)