crokta_liveness 1.4.1

A Flutter SDK for Face Liveness Verification, passive/active liveness UI.

Crokta Liveness SDK

A production-grade, enterprise-ready biometric liveness verification solution designed for Flutter applications utilizing the FaceGuard biometric suite. It aggregates and validates AWS Rekognition and Google ML Kit Face Liveness sessions.

Features

1. Anti-Spoof Defense: Supports passive and active challenge fallbacks to prevent screen replay, deepfakes, printed/synthetic media attacks, etc.
2. Provider Abstraction: Swappable liveness engines (AWS Rekognition, Google ML Kit, Mock) dynamically without changes to downstream client apps.
3. KYC Upgrade Flow: Supports upgrade checks (Mutual Exclusivity BVN $\leftrightarrow$ NIN) using a strict comparison against the onboarding reference photo with a 0.40 similarity threshold.
4. Advanced ML Kit Gestures: Features eye-blink detection alongside head movements (Tilt Up, Tilt Down, Tilt Sideways).

---

1. Project Integration

Dependencies

In your app's pubspec.yaml, add the dependency:

dependencies:
  crokta_liveness:
    path: path/to/liveness_sdk

Android Permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.front" />

iOS Configuration

The native AWS Face Liveness UI on iOS requires linking native AWS Amplify packages and initializing them at app startup.

1. Add Swift Package Dependencies

This step must be done in Xcode:

1. Open your project's iOS workspace (e.g., ios/Runner.xcworkspace) in Xcode.
2. Go to File → Add Package Dependencies...
3. Add the following packages and link their products to your Runner target:
   • https://github.com/aws-amplify/amplify-swift (Select Amplify and AWSCognitoAuthPlugin)
   • https://github.com/aws-amplify/amplify-ui-swift-liveness (Select FaceLiveness)

2. Configure Amplify at Launch

Update your ios/Runner/AppDelegate.swift to import the native Amplify libraries and configure it with the Cognito configuration bundled inside the SDK.

Replace or update your AppDelegate.swift as follows:

import Flutter
import UIKit
import Amplify
import AWSCognitoAuthPlugin
import crokta_liveness

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    configureAmplify()
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  private func configureAmplify() {
    guard !Amplify.isConfigured else { return }
    do {
      try Amplify.add(plugin: AWSCognitoAuthPlugin())
      
      // Load the Cognito config bundled inside the crokta_liveness SDK resource bundle.
      // This avoids the need to author or hardcode amplifyconfiguration.json in the client app.
      if let url = CroktaLivenessPlugin.amplifyConfigurationURL() {
        let data = try Data(contentsOf: url)
        let config = try JSONDecoder().decode(AmplifyConfiguration.self, from: data)
        try Amplify.configure(config)
      } else {
        try Amplify.configure() // Fallback to main bundle config
      }
      print("AppDelegate: Amplify configured successfully for Face Liveness.")
    } catch {
      print("AppDelegate: Failed to configure Amplify: \(error)")
    }
  }
}

3. Update Podfile

Ensure your ios/Podfile specifies iOS 13.0 or higher and enables frameworks:

platform :ios, '13.0'
use_frameworks!

4. Configure Permissions

Add the camera and microphone usage descriptions to your ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app requires camera access to perform biometric face liveness checks during verification actions.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required during the liveness verification session.</string>

5. Build and Run

After completing the setup:

cd ios
pod install
cd ..
flutter run

Note: The native AWS Face Liveness stream requires a physical iOS device and will not function on an iOS Simulator.

---

2. SDK Initialization

Initialize the SDK once during application startup (e.g., inside main.dart):

import 'package:crokta_liveness/crokta_liveness.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await LivenessSDK.initialize(
    backendUrl: 'https://api.staging.faceguard.com',
    apiKey: 'your-app-api-key',
    environment: LivenessEnvironment.staging,
    timeoutSeconds: 15,
  );

  runApp(const MyApp());
}

---

3. Launching Verification

Call LivenessSDK.verify(context) when intercepting secure flows.

Example: Onboarding Verification

void onOnboardingTriggered(BuildContext context) async {
  // 1. Launch liveness scanning interface
  final result = await LivenessSDK.verify(
    context,
    userId: 'customer-uuid-created-on-backend',
    kycType: 'bvn',
    kycNumber: '11122233344',
    verificationType: 'ONBOARDING',
    channel: 'personal',
  );

  if (!result.success || result.status != LivenessStatus.pass) {
    showErrorBlock('Biometric verification failed.');
    return;
  }

  proceedWithRegistration();
}

Example: KYC Upgrade Verification

void onKycUpgradeTriggered(BuildContext context, String customerId) async {
  final result = await LivenessSDK.verify(
    context,
    userId: customerId,
    kycType: 'nin',
    kycNumber: '99988877766',
    verificationType: 'KYC_UPGRADE',
    channel: 'personal',
  );

  if (!result.success || result.status != LivenessStatus.pass) {
    showErrorBlock('KYC Upgrade biometric check failed.');
    return;
  }

  proceedWithUpgradeCompletion(result.sessionId);
}

Example: Face Verification Check (No KYC details required)

void onFaceVerificationTriggered(BuildContext context, String customerId, String channel) async {
  final result = await LivenessSDK.verify(
    context,
    userId: customerId,
    verificationType: 'VERIFICATION',
    channel: channel,
  );

  if (!result.success || result.status != LivenessStatus.pass) {
    showErrorBlock('Face Match comparison failed. Access blocked.');
    return;
  }

  proceedWithTransaction();
}