flutter_pua_auth_ios

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

📋 Overview

This is a platform-specific implementation package for iOS. It should be used together with the main flutter_pua_auth package. This package handles all iOS-specific functionality including PUA SDK integration, Face ID/Touch ID authentication via LocalAuthentication framework, 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_ios: ^1.0.0

🔧 iOS Setup Requirements

1. Add PUA Framework

The PUA SDK framework (PUA.framework) is included in this package at:

flutter_pua_auth_ios/ios/Frameworks/PUA.framework

The framework is automatically linked via the podspec. No manual configuration needed.

2. Add Required Permissions

Edit ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for face monitoring and authentication</string>

<key>NSFaceIDUsageDescription</key>
<string>This app needs Face ID access for biometric authentication</string>

3. Configure Podfile

The plugin's podspec automatically handles framework integration. Make sure your ios/Podfile includes:

platform :ios, '12.0'

target 'Runner' do
  use_frameworks!
  use_modular_headers!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

Then run:

cd ios
pod install

4. Import Platform Package

In your app's main.dart, import the iOS 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());
}

✨ iOS-Specific Features

Supported Biometric Types

  • ✅ Face ID - Full support via PUA SDK and LocalAuthentication
  • ✅ Touch ID - Full support via LocalAuthentication
  • ✅ Passcode - Fallback authentication method

PUA SDK Integration

  • ✅ PUA SDK v2.0 - Full support with version detection
  • ✅ Face Monitoring - Real-time face detection from camera
  • ✅ Multi-Face Detection - Detects when multiple faces are present
  • ✅ Eye Closure Detection - Timeout-based approach
  • ✅ Low Light Warnings - onLightWarning() callback support

iOS-Specific Parameters

Parameter Status Notes
eyesOffScreenTime ✅ Working Timeout in seconds (0.25-30.0)
numberOfFacesAllowed ✅ Working Maximum allowed faces
refreshRate ✅ Working Instant, fast, medium, light
lowLightThreshold ✅ Working Lux threshold (200-2000)
eyeClosedProbabilityThreshold ❌ Not Available iOS uses timeout-based approach

Features

  1. Version Detection: iOS SDK exposes version information via getPuaVersion()
  2. Low Light Warnings: onLightWarning() callback is fully supported
  3. Exact Face Count: Face count is exact, not estimated
  4. Timeout-Based Eye Detection: Uses eyesOffScreenTime for eye closure detection

📱 Platform Support

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

iOS Simulator Limitations

What Works:

  • ✅ Basic biometric authentication (authenticateUser()) - Uses LocalAuthentication
  • ✅ isBiometricAvailable() - Returns true if Face ID/Touch ID is enabled
  • ✅ getAvailableBiometrics() - Returns available biometric types
  • ✅ configureApiKey() - API key can be configured

What Doesn't Work:

  • ❌ PUA SDK Face Monitoring - PUA.framework is device-only (arm64), not available on simulator
  • ❌ Continuous face detection - startFaceMonitoring() will not detect faces
  • ❌ Real-time face counting - Face count callbacks won't be triggered
  • ❌ Screen locking based on face detection - Not available

To Test Face Monitoring:

  • Use a real iOS device with Face ID
  • Enable Face ID in Settings → Face ID & Passcode
  • Grant camera permission when prompted

🐛 Troubleshooting

Issue: "PUA SDK not available on simulator"

Solution: This is expected. PUA SDK requires a real iOS device. The plugin will automatically fall back to LocalAuthentication on simulators.

Issue: "MissingPluginException"

Solution: Make sure you:

  1. Import the platform package in your main.dart: 
    import 'package:flutter_pua_auth_ios/flutter_pua_auth_ios.dart';
  2. Run flutter clean and flutter pub get
  3. Run cd ios && pod install
  4. Rebuild the app

Issue: Face ID not working

Solution:

  1. Check that Face ID is enabled in Settings → Face ID & Passcode
  2. Make sure NSFaceIDUsageDescription is set in Info.plist
  3. Grant Face ID permission when prompted
  4. Use a real device (not simulator)

Issue: Camera permission denied

Solution:

  1. Add NSCameraUsageDescription to Info.plist
  2. Grant camera permission when prompted
  3. Check Settings → Privacy → Camera to ensure permission is granted

Issue: Framework not found

Solution:

  1. Run cd ios && pod install
  2. Clean build folder in Xcode: Product → Clean Build Folder
  3. Rebuild the project

📚 Additional Resources

💡 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_ios to your pubspec.yaml and follow the setup instructions above.

📄 License

See the LICENSE file for details.

🔗 Related Packages

Libraries

flutter_pua_auth_ios