capacitor-aws-face-liveness

A Capacitor plugin that starts an AWS Face Liveness (liveness detection) flow on Android, exposing a typed TypeScript API for Ionic / Capacitor / Angular apps.

Target: Capacitor v8+ (recommended).
Status: Android implementation ready. iOS structure can be added/extended as needed.

Features

• Launches a native Face Liveness flow on Android
• Returns a normalized result object (success, status, message, confidenceScore, etc.)
• Basic UI customization (title, instruction, theme color, timeout)
• Fully typed API via definitions.ts

Requirements

• Node 18+ recommended
• Capacitor v8+
• Android Studio
• A backend capable of generating a Face Liveness session (AWS Rekognition CreateFaceLivenessSession)

Installation

Install as a local plugin (recommended during development)

From your Ionic/Capacitor app folder:

npm install capacitor-aws-face-liveness
npx cap sync android

Whenever you change the plugin code, reinstall it and run npx cap sync android again.

Android Permissions

Android requires camera permission at runtime.

In your app, request camera permission before starting the liveness flow:

import { Camera } from '@capacitor/camera';

await Camera.requestPermissions({ permissions: ['camera'] });

The plugin may declare permissions in its AndroidManifest, but runtime permission is still required on modern Android versions.

Usage (Ionic / Angular)

Import and call

import { AwsFaceLiveness } from 'capacitor-aws-face-liveness';

const result = await AwsFaceLiveness.startLivenessDetection({
  sessionId: 'YOUR_SESSION_ID',
  region: 'us-east-1',
  credentials: {
    accessKeyId: 'AKIA...',
    secretAccessKey: '...',
    sessionToken: '...' // optional
  },
  customTitle: 'Position your face',
  customInstruction: 'Make sure your face is clearly visible',
  themeColor: '#15803d',
  timeoutMs: 60000
});

console.log('Liveness result:', result);

Example with camera permission check

import { Camera } from '@capacitor/camera';
import { AwsFaceLiveness } from 'capacitor-aws-face-liveness';

async function startLiveness() {
  const perm = await Camera.requestPermissions({ permissions: ['camera'] });
  if ((perm as any)?.camera !== 'granted') {
    throw new Error('Camera permission denied');
  }

  return AwsFaceLiveness.startLivenessDetection({
    sessionId: 'YOUR_SESSION_ID',
    region: 'us-east-1',
    credentials: {
      accessKeyId: 'AKIA...',
      secretAccessKey: '...'
    },
    timeoutMs: 60000
  });
}

API Reference

startLivenessDetection(options: FaceLivenessOptions): Promise<FaceLivenessResult>

Starts the Face Liveness flow.

FaceLivenessOptions

| Field | Type | Required | Description | |------|------|----------|-------------| | sessionId | string | ✅ | Session ID created by your backend (AWS Rekognition CreateFaceLivenessSession) | | region | string | ✅ | AWS region (us-east-1, eu-west-1, etc.) | | credentials.accessKeyId | string | ✅ | AWS Access Key | | credentials.secretAccessKey | string | ✅ | AWS Secret Key | | credentials.sessionToken | string | ❌ | Session token (temporary credentials) | | customTitle | string | ❌ | Custom UI title | | customInstruction | string | ❌ | Custom UI instruction text | | themeColor | string | ❌ | Primary theme color (hex), e.g. #15803d | | timeoutMs | number | ❌ | Timeout in milliseconds (default: 60000) |

FaceLivenessResult

| Field | Type | Description | |------|------|-------------| | success | boolean | Whether the flow succeeded | | status | 'completed' \| 'cancelled' \| 'timeout' \| 'error' | Final status | | message | string | Human-readable message | | sessionId | string? | Related sessionId | | confidenceScore | number? | Score (0–100) when status is completed | | error.code | string? | Error code (if any) | | error.message | string? | Error message (if any) |

Plugin Structure

• src/ — TypeScript plugin code
• android/ — Android (Kotlin) implementation
• ios/ — iOS structure (if applicable)
• dist/ — compiled output produced by npm run build

Developing the Plugin

Build the plugin

Inside the plugin folder:

npm install
npm run build

Use updated plugin in your app

Inside your app folder:

npm uninstall capacitor-aws-face-liveness
npm install file:../../Plugins_Capacitor_Customizados/capacitor-aws-face-liveness
npx cap sync android

Running on Android

Inside your app folder:

ionic build
npx cap sync android
npx cap open android

Then in Android Studio, click Run.

Troubleshooting

“Plugin not implemented” / method not found

• Run npx cap sync android
• Open Android Studio and Sync Gradle
• Ensure native plugin name matches the JS registration name (AwsFaceLiveness)

Changes to the local plugin don’t show up

• Reinstall the plugin (npm uninstall then npm install file:...)
• Run npx cap sync android again

Camera permission denied

• Request permissions via Camera.requestPermissions()
• Ensure camera permission is enabled in Android app settings

License

MIT