flutter_pua_auth_ios 1.0.0

iOS implementation of the Flutter PUA Auth plugin

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.

📋 Overview

This is a platform-specific implementation package for iOS. It should be used together with the main flutter_pua_auth package.

⚠️ Important: This package is not meant to be used standalone. Always use it with the main flutter_pua_auth package.

📦 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

• Main Package README - Complete documentation
• Example App - Working example implementation
• API Documentation - Complete API reference
• Platform Setup Guide - Detailed setup instructions
• iOS Authentication Types - iOS-specific authentication details
• Simulator Guide - Testing on iOS Simulator

📄 License

See the LICENSE file for details.

🔗 Related Packages

• flutter_pua_auth - Main package (required)
• flutter_pua_auth_android - Android implementation