flutter_pua_auth_android

Android implementation of the Flutter PUA Auth plugin. This package provides the native Android integration for biometric authentication and continuous face monitoring using The Whisper Company's PUA SDK. It includes the Android PUA SDK wrapper, method channel handlers, and all Android-specific configuration required for face detection and biometric authentication on Android devices.

📋 Overview

This is a platform-specific implementation package for Android. It should be used together with the main flutter_pua_auth package. This package handles all Android-specific functionality including PUA SDK integration, camera access, biometric authentication via BiometricPrompt, and real-time face monitoring from the device camera.

⚠️ Important: This package is not meant to be used standalone. Always use it with the main flutter_pua_auth package. For a complete working example, see the example app in the main package repository.

📦 Installation

Add both packages to your pubspec.yaml:

dependencies:
  flutter_pua_auth: ^1.0.0
  flutter_pua_auth_android: ^1.0.0

🔧 Android Setup Requirements

1. Add PUA SDK AAR File

The PUA SDK AAR file (pua-release.aar) is included in this package at:

flutter_pua_auth_android/android/libs/pua-release.aar

Configure your app's android/app/build.gradle:

android {
    // ... other config
    
    repositories {
        flatDir {
            dirs project(':flutter_pua_auth_android').file('libs')
        }
    }
}

dependencies {
    // PUA SDK AAR
    implementation(name: 'pua-release', ext: 'aar')
    
    // ... other dependencies
}

2. Add Required Permissions

Edit android/app/src/main/AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <!-- Required permissions for PUA SDK -->
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.USE_BIOMETRIC" />
    <uses-permission android:name="android.permission.USE_FINGERPRINT" />
    <uses-feature android:name="android.hardware.camera.any" />
    
    <application ...>
        <!-- Your app configuration -->
    </application>
</manifest>

3. Add Required Dependencies

The PUA SDK requires several Android dependencies. Add these to android/app/build.gradle:

dependencies {
    // PUA SDK dependencies
    implementation 'androidx.camera:camera-core:1.3.0'
    implementation 'androidx.camera:camera-camera2:1.3.0'
    implementation 'androidx.camera:camera-lifecycle:1.3.0'
    implementation 'com.google.mlkit:face-detection:16.1.5'
    implementation 'androidx.biometric:biometric:1.1.0'
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3'
    implementation 'androidx.room:room-runtime:2.6.0'
    
    // ... other dependencies
}

4. Import Platform Package

In your app's main.dart, import the Android implementation to trigger auto-registration:

import 'package:flutter/material.dart';
// Import platform packages to trigger auto-registration
import 'package:flutter_pua_auth_android/flutter_pua_auth_android.dart';
import 'package:flutter_pua_auth_ios/flutter_pua_auth_ios.dart';
import 'package:flutter_pua_auth/flutter_pua_auth.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Configure PUA API key
  await FlutterPuaAuth.instance.configureApiKey("your-api-key-here");
  
  runApp(MyApp());
}

✨ Android-Specific Features

Supported Biometric Types

• ✅ Fingerprint - Full support via BiometricPrompt
• ✅ Face Unlock - Limited support (depends on device)
• ⚠️ Face ID - Not available (iOS only)

PUA SDK Integration

• ✅ PUAOne Architecture - Automatically detected and configured
• ✅ PWATwo Architecture - Automatically detected and configured
• ✅ Face Monitoring - Real-time face detection from camera
• ✅ Multi-Face Detection - Detects when multiple faces are present
• ✅ Eye Closure Detection - Uses eyeClosedProbabilityThreshold parameter

Android-Specific Parameters

Parameter	Status	Notes
eyeClosedProbabilityThreshold	✅ Working	Controls sensitivity of eye closure detection (0.0-1.0)
numberOfFacesAllowed	✅ Working	Set via PUAOne/PWATwo sub-objects
refreshRate	⚠️ Partial	May not be set correctly
lowLightThreshold	⚠️ Partial	May not be set correctly
eyesOffScreenTime	❌ Not Supported	Android uses eyeClosedProbabilityThreshold instead

Limitations

1. Version Detection: Android SDK doesn't expose version information
2. Low Light Warnings: onLightWarning() callback is not available in Android SDK
3. Face Count Estimation: For IntruderFaceDetected, face count is estimated (last known + 1)
4. BiometricPrompt Face Unlock: Cannot force face unlock when both fingerprint and face unlock are available

📱 Platform Support

Device Type	Status	Notes
Real Android Device	✅ Fully Supported	All features work
Android Emulator	⚠️ Limited	Basic biometric auth only, no face monitoring

🐛 Troubleshooting

Issue: "PUA use blocked, please contact your provider"

Solution: This means the PUA SDK API key is invalid or not configured. Make sure you:

1. Have a valid API key from The Whisper Company
2. Call configureApiKey() before using any PUA features
3. Have internet connection for initial SDK authentication

Issue: "MissingPluginException"

Solution: Make sure you:

1. Import the platform package in your main.dart:

   import 'package:flutter_pua_auth_android/flutter_pua_auth_android.dart';
   

2. Run flutter clean and flutter pub get
3. Rebuild the app

Issue: Face count is incorrect

Solution: Android estimates face count for IntruderFaceDetected events. The actual count may be higher than reported. This is a limitation of the Android PUA SDK.

Issue: BiometricPrompt shows fingerprint instead of face unlock

Solution: Android's BiometricPrompt automatically chooses the available biometric. You cannot force face unlock when both are available. This is an Android platform limitation.

📚 Additional Resources

• Main Package README - Complete documentation
• Example App - Working example implementation
• API Documentation - Complete API reference
• Platform Setup Guide - Detailed setup instructions

💡 Example

This package is a platform implementation and should be used with the main flutter_pua_auth package. For a complete working example that demonstrates both Android and iOS functionality, see the example app in the main package repository. The example includes:

• Biometric authentication setup
• Face monitoring implementation
• Screen locking/unlocking logic
• Settings configuration
• Error handling

To use this package, add both flutter_pua_auth and flutter_pua_auth_android to your pubspec.yaml and follow the setup instructions above.

📄 License

See the LICENSE file for details.

🔗 Related Packages

• flutter_pua_auth - Main package (required)
• flutter_pua_auth_ios - iOS implementation