flutter_identity_comparison_sdk 1.1.1

A Flutter SDK for identity comparison and liveness checks by Dikript Solutions.

Flutter Identity Comparison SDK

A Flutter SDK for identity verification using liveness checks and ID verification. This SDK provides a seamless integration for applications requiring identity verification across multiple platforms (Android, iOS, and Web).

Table of Contents

• Features
• Installation
• Usage
  • Basic Implementation
  • Advanced Configuration
• Platform-Specific Considerations
  • Android
  • iOS
  • Web
• API Reference
• Troubleshooting
• Recent Updates
• License

Features

• Liveness Detection: Verify that the user is a real person and not a photo or video.
• Identity Verification: Compare the user's face with their ID document.
• Cross-Platform Support: Works on Android, iOS, and Web platforms.
• Customizable UI: Easily customize the appearance to match your app's design.
• Secure: All processing is done through secure API endpoints.
• Timeout Handling: Prevents hanging requests with configurable timeouts.
• Improved Error Feedback: Clear error messages and loading states.

Installation

Add the Flutter Identity Comparison SDK to your pubspec.yaml file:

dependencies:
  flutter_identity_comparison_sdk:
    git:
      url: https://github.com/yourusername/flutter_identity_comparison_sdk.git
      ref: main

Or, if you're using a local copy:

dependencies:
  flutter_identity_comparison_sdk:
    path: ../flutter_identity_comparison_sdk

Then run:

flutter pub get

Dependencies

This SDK relies on the following packages:

• camera: ^0.10.6
• google_mlkit_face_detection: ^0.3.0
• google_mlkit_commons: ^0.2.0
• http: ^0.13.5

Usage

Basic Implementation

1. Import the package:

import 'package:flutter_identity_comparison_sdk/flutter_identity_comparison_sdk.dart';

2. Add the IdentityComparisonWidget to your app:

class _MyAppState extends State<MyApp> {
  void _startIdentityVerification() {
    Navigator.of(context).push(
      MaterialPageRoute(
        builder: (context) => Scaffold(
          appBar: AppBar(
            title: const Text('Identity Verification'),
          ),
          body: IdentityComparisonWidget(
            name: 'Your App Name',
            apiUrl: 'https://your-api-endpoint.com',
            apiKey: 'your-api-key',
            onIdentityComparisonResult: (result) {
              print('Identity comparison result: ${result.isMatch}');
              // Handle the result
            },
          ),
        ),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('My App'),
        ),
        body: Center(
          child: ElevatedButton(
            onPressed: _startIdentityVerification,
            child: const Text('Start Identity Verification'),
          ),
        ),
      ),
    );
  }
}

Advanced Configuration

The IdentityComparisonWidget accepts several parameters for customization:

IdentityComparisonWidget(
  name: 'Your App Name',
  apiUrl: 'https://your-api-endpoint.com',
  apiKey: 'your-api-key',
  onIdentityComparisonResult: (result) {
    // Handle the result
  },
  primaryColor: Colors.blue,
  secondaryColor: Colors.white,
  fontFamily: 'Roboto',
  idTypes: const ['National ID', 'Passport', 'Driver\'s License'],
  instructions: 'Please position your face within the frame for verification.',
  showLogo: true,
  logoPath: 'assets/logo.png',
)

API Service Configuration

You can customize the timeout duration for API requests by passing a timeout parameter to the widget:

IdentityComparisonWidget(
  name: 'Your App Name',
  apiUrl: 'https://your-api-endpoint.com',
  apiKey: 'your-api-key',
  onIdentityComparisonResult: (result) {
    // Handle the result
  },
  // Set a custom timeout of 45 seconds
  apiTimeout: const Duration(seconds: 45),
)

By default, API requests will timeout after 30 seconds to prevent hanging processes.

Platform-Specific Considerations

Android

Permissions

Add the following permissions to your AndroidManifest.xml file:

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

Troubleshooting Android Issues

1. Camera Not Working: Ensure you have requested camera permissions at runtime.

2. Face Detection Issues: The SDK uses Google ML Kit for face detection. Make sure your device supports Google Play Services.

3. Gradle Build Errors: If you encounter duplicate class errors, check for conflicting dependencies in your app's build.gradle file. You may need to exclude certain transitive dependencies:

implementation('com.google.android.gms:play-services-mlkit-face-detection:16.2.0') {
    exclude group: 'com.google.android.gms', module: 'play-services-base'
}

4. NDK Version Compatibility: Ensure your Android NDK version is compatible with the ML Kit dependencies. We recommend using NDK version 21.4.7075529 or later.

iOS

Permissions

Add the following to your Info.plist file:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for identity verification</string>

Troubleshooting iOS Issues

1. Camera Access: If the camera doesn't initialize, check that you've properly set up the NSCameraUsageDescription in your Info.plist.

2. Build Errors: If you encounter build errors related to Pods, try:

   cd ios
   pod deintegrate
   pod install
   

3. Face Detection Performance: On older iOS devices, face detection might be slower. Consider adding a loading indicator during processing.

Web

Browser Compatibility

The SDK supports modern browsers including:

• Chrome (recommended)
• Firefox
• Safari
• Edge

Web-Specific Limitations

1. Camera Access: The web version uses the browser's getUserMedia API for camera access. This requires:

   • The site to be served over HTTPS (except for localhost)
   • User permission to access the camera

2. Face Detection: On web platforms, face detection is simplified compared to mobile platforms:

   • The SDK automatically enables the capture button without requiring face detection
   • Users should ensure their face is clearly visible before capturing

3. Performance: Face detection and processing may be slower on web platforms compared to native mobile apps.

4. Browser Storage: The SDK uses browser storage for temporary data. If you encounter "QUOTA_BYTES exceeded" errors, consider:

   • Reducing the size of stored data
   • Clearing browser storage before initializing the SDK

Troubleshooting Web Issues

1. Camera Not Starting: If the camera doesn't start on web:

   • Check that your site is served over HTTPS
   • Ensure the user has granted camera permissions
   • Verify that the browser supports getUserMedia

2. "Platform._operatingSystem" Error: This error occurs when using platform-specific code on web. The SDK handles this internally by using the PlatformHelper class.

3. Face Detection Errors: If you encounter errors related to face detection on web:

   • The SDK automatically disables ML Kit face detection on web
   • Users can still capture photos without face detection

API Reference

IdentityComparisonWidget

The main widget for identity verification.

Constructor

IdentityComparisonWidget({
  Key? key,
  required String apiKey,
  required String name,
  required String apiUrl,
  VoidCallback? onClose,
  Function(IdentityComparisonResponse)? onIdentityComparisonResult,
  String? modelPath,
  List<IdType>? idTypes,
})

Parameters

Parameter	Type	Required	Description
apiKey	String	Yes	Your API key for authentication
name	String	Yes	The name of your application
apiUrl	String	Yes	The URL for the identity comparison API endpoint
onClose	VoidCallback?	No	Callback function called when the widget is closed
onIdentityComparisonResult	Function(IdentityComparisonResponse)?	No	Callback function called with the result of the identity comparison
modelPath	String?	No	Path to the ML models (optional)
idTypes	List<IdType>?	No	List of ID types to display in the dropdown (optional)

IdType

Represents an ID type option for the dropdown.

Constructor

const IdType({
  required String value,
  required String label,
})

Parameters

Parameter	Type	Required	Description
value	String	Yes	Value to be sent to the API
label	String	Yes	Display label for the dropdown

IdentityComparisonResponse

Response from the identity comparison API.

Property	Type	Description
isMatch	bool	Whether the face matches the ID
confidence	double	Confidence score (0-1)
message	String?	Additional information
errorCode	String?	Error code if applicable
timestamp	DateTime	When the verification was performed

Customizing ID Types

You can customize the ID types that are displayed in the dropdown by providing a list of IdType objects to the idTypes parameter:

import 'package:flutter/material.dart';
import 'package:flutter_identity_comparison_sdk/flutter_identity_comparison_sdk.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Custom ID Types Example'),
        ),
        body: Center(
          child: ElevatedButton(
            onPressed: () {
              Navigator.of(context).push(
                MaterialPageRoute(
                  builder: (context) => const VerificationScreen(),
                ),
              );
            },
            child: const Text('Start Verification'),
          ),
        ),
      ),
    );
  }
}

class VerificationScreen extends StatelessWidget {
  const VerificationScreen({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    // Custom ID types
    final customIdTypes = [
      const IdType(value: 'NIN', label: 'National ID Number'),
      const IdType(value: 'PASSPORT', label: 'International Passport'),
      const IdType(value: 'DRIVERSLICENSE', label: 'Driver\'s License'),
      const IdType(value: 'VOTERSCARD', label: 'Voter\'s Card'),
    ];

    return Scaffold(
      appBar: AppBar(
        title: const Text('Identity Verification'),
      ),
      body: IdentityComparisonWidget(
        apiKey: 'your-api-key',
        name: 'Your App Name',
        apiUrl: 'https://your-api-endpoint.com',
        idTypes: customIdTypes,
        onIdentityComparisonResult: (result) {
          print('Identity comparison result: ${result.isMatch}');
          // Handle the result
          if (result.isMatch) {
            // Identity verified
          } else {
            // Identity verification failed
          }
        },
      ),
    );
  }
}

By default, the widget displays the following ID types:
- BVN
- Phone Number
- FRSC
- NIN

You can override these with your own list of ID types as shown in the example above.

## Troubleshooting

### Common Issues

1. **Camera Initialization Failed**
   - Check camera permissions
   - Ensure no other app is using the camera
   - Restart the app

2. **Face Detection Not Working**
   - Ensure adequate lighting
   - Position face clearly in the frame
   - Check if Google Play Services is available (Android)

3. **API Connection Errors**
   - Verify internet connectivity
   - Check API URL and key
   - Ensure the API endpoint is accessible

4. **Platform-Specific Errors**
   - See the platform-specific sections above

### Logging

Enable debug logging for troubleshooting:

```dart
FlutterIdentityComparisonSdk.enableDebugLogs(true);

Recent Updates

Version 1.1.1

• Fixed issue where "Capture Photo" button remained visible during identity comparison processing
• Added loading overlay to indicate when identity verification is in progress
• Implemented timeout handling for API requests to prevent hanging requests
• Improved error handling for identity comparison process

Version 1.1.0

• Added support for customizable ID types through the new idTypes parameter
• Added IdType interface to represent ID type options
• Updated documentation and examples to demonstrate the new feature

License

This project is licensed under the MIT License - see the LICENSE file for details.