Apex KYC #

Author #

Crafted with love by Bagus Subagja ❤️

Feel free to fork and modify this package to suit your needs - that's much more enjoyable than stealing or claiming my code 😊

Preview 🪟 #

Watch Demo Video

Features ✨ #

🔐 Complete KYC Flow #

• 📄 Document Type Selection - Support for Passport, National ID, Driving License, and ID Card
• 📷 Document Capture - Front and back side capture with image quality optimization
• 🔄 Automatic Upload - Seamless document upload to backend
• 📊 Progress Tracking - Multiple progress indicator styles (linear, steps, gradient, minimal)
• 🎨 Customizable Themes - Light/dark mode support with custom color schemes
• 🏢 Company Branding - Optional logo and company name display

👤 Liveness Detection #

• 📱 Real-time Face Detection - Powered by Google ML Kit
• 🎲 Randomized Challenge Sequence - Dynamic challenge generation for enhanced security
• 💫 Cross-platform Support - iOS & Android compatibility
• ✅ High Accuracy Verification - Advanced liveness detection algorithms
• 🎭 Customizable Challenge Labels - Support for multiple languages
• ⏱️ Automatic Cooldown - Security feature to prevent brute force attempts
• 🎯 Flexible Configuration - Extensive customization options

🛠️ Developer Experience #

• 🚀 Simple Integration - Easy-to-use API with minimal setup
• 📦 Backend Integration - Built-in API client for verification services
• 🔧 Comprehensive Configuration - Fine-tune every aspect of the verification flow
• 📝 Error Handling - Robust error handling with clear error messages
• 🧪 Testing Support - Example app with multiple test scenarios

Installation 📦 #

Add this to your package's pubspec.yaml file:

dependencies:
  apex_kyc: ^1.0.0

Then run:

flutter pub get

Quick Start 🚀 #

1. Complete KYC Flow (Recommended) #

The easiest way to integrate KYC verification is using the complete flow widget:

import 'package:apex_kyc/index.dart';

void main() {
  // Initialize SDK configuration
  ApexKycConfig.initialize(
    baseUrl: 'https://your-backend-api.com',
    apiKey: 'your-api-key', // Optional
    enableLogging: true, // Enable for debugging
    enableManualCapture: true,
    companyName: 'Your Company',
    companyLogoUrl: 'https://your-logo-url.com/logo.png',
  );
  
  runApp(MyApp());
}

// In your widget
ApexKycFlowWidget(
  applicantId: 'applicant-id-from-backend',
  progressStyle: ProgressIndicatorStyle.steps,
  showProgress: true,
  showTips: true,
  showCompanyBranding: true,
  theme: KycTheme.defaultGreen(), // Or custom theme
  onComplete: (verification) {
    print('Verification completed: ${verification.requestId}');
    print('Status: ${verification.verificationStatus}');
    print('Liveness Passed: ${verification.livenessPassed}');
  },
  onError: (error) {
    print('Error: $error');
  },
)

2. Liveness Detection Only #

If you only need liveness detection without document verification:

import 'package:apex_kyc/index.dart';

final result = await FlutterLivenessDetectionRandomizedPlugin.instance.livenessDetection(
  context: context,
  config: LivenessDetectionConfig(
    // Camera & Image Settings
    cameraResolution: ResolutionPreset.medium,
    imageQuality: 100,
    isEnableMaxBrightness: true,
    
    // Detection Settings
    durationLivenessVerify: 60,
    showDurationUiText: false,
    startWithInfoScreen: true,
    
    // UI Settings
    isDarkMode: false,
    showCurrentStep: true,
    isEnableSnackBar: true,
    shuffleListWithSmileLast: true,
    
    // Security Features
    enableCooldownOnFailure: true,
    maxFailedAttempts: 3,
    cooldownMinutes: 10,
  ),
);

if (result != null && result.isNotEmpty) {
  // Liveness detection successful
  print('Face captured: ${result.length} frames');
} else {
  // Detection failed or cancelled
  print('Detection failed');
}

Configuration 📋 #

SDK Configuration #

ApexKycConfig.initialize(
  baseUrl: 'https://your-backend-api.com', // Required
  apiKey: 'your-api-key', // Optional
  timeoutSeconds: 30, // Default: 30
  enableLogging: false, // Default: false
  enableManualCapture: true, // Default: true
  companyName: 'Your Company', // Optional
  companyLogoUrl: 'https://your-logo-url.com/logo.png', // Optional
);

Liveness Detection Configuration #

Camera & Image Settings

• cameraResolution: Camera quality (ResolutionPreset.low/medium/high) - Default: high
• imageQuality: Output image quality 0-100 - Default: 100
• isEnableMaxBrightness: Auto brightness adjustment - Default: true

Detection Settings

• durationLivenessVerify: Detection timeout in seconds - Default: 45
• showDurationUiText: Show countdown timer - Default: false
• startWithInfoScreen: Show tutorial before detection - Default: false

UI Settings

• isDarkMode: Dark theme mode - Default: true
• showCurrentStep: Show current step number - Default: false
• isEnableSnackBar: Show success/failure notifications - Default: true
• shuffleListWithSmileLast: Randomize challenges with smile at end - Default: true

Customization

• useCustomizedLabel: Enable custom challenge labels - Default: false
• customizedLabel: Custom labels for each challenge type

Security Features

• enableCooldownOnFailure: Enable cooldown after failed attempts - Default: true
• maxFailedAttempts: Number of failures before cooldown - Default: 3
• cooldownMinutes: Cooldown duration in minutes - Default: 10

KYC Flow Widget Configuration #

ApexKycFlowWidget(
  applicantId: 'required-applicant-id',
  progressStyle: ProgressIndicatorStyle.linear, // linear, steps, gradient, minimal
  showProgress: true,
  showTips: true,
  showCompanyBranding: false,
  theme: KycTheme.defaultGreen(), // Custom theme
  onComplete: (verification) { /* Handle success */ },
  onError: (error) { /* Handle error */ },
)

Customized Challenge Labels 🎭 #

You can customize challenge labels or skip certain challenges:

LivenessDetectionConfig(
  useCustomizedLabel: true,
  customizedLabel: LivenessDetectionLabelModel(
    blink: 'Kedipkan Mata', // Custom label
    lookDown: '', // Empty string = skip challenge
    lookLeft: null, // null = use default "Look LEFT"
    lookRight: 'Putar ke Kanan', // Custom label
    lookUp: 'Lihat ke Atas', // Custom label
    smile: null, // null = use default "Smile"
  ),
)

Rules:

• Use empty string '' to skip a challenge
• Use null to keep default label
• Provide custom string for personalized labels
• When useCustomizedLabel: true, customizedLabel must not be null

Cooldown Feature ⏱️ #

The plugin includes an automatic cooldown mechanism to prevent brute force attempts:

• Configurable number of failed attempts before cooldown
• Configurable cooldown duration
• Countdown timer only decreases when app is active
• Cooldown state persists through app restarts
• Users see a countdown screen during cooldown period

LivenessDetectionConfig(
  enableCooldownOnFailure: true,
  maxFailedAttempts: 3, // Failed attempts before cooldown
  cooldownMinutes: 10, // Cooldown duration
)

Progress Indicator Styles 📊 #

The KYC flow widget supports multiple progress indicator styles:

• ProgressIndicatorStyle.linear - Simple linear progress bar
• ProgressIndicatorStyle.steps - Step-based progress with circles
• ProgressIndicatorStyle.gradient - Gradient progress bar with shadow
• ProgressIndicatorStyle.minimal - Minimal thin progress bar

Theme Customization 🎨 #

Create custom themes for the KYC flow:

final customTheme = KycTheme(
  primaryColor: Colors.blue,
  secondaryColor: Colors.blueAccent,
  backgroundColor: Colors.white,
  textColor: Colors.black87,
  // ... more theme options
);

ApexKycFlowWidget(
  theme: customTheme,
  // ...
)

Platform Setup 🔧 #

Android #

Add camera permission to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA"/>

Minimum SDK version: 23

iOS #

Add camera usage description to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for KYC verification and liveness detection</string>

Complete Example 💡 #

import 'package:flutter/material.dart';
import 'package:apex_kyc/index.dart';

void main() {
  // Initialize SDK
  ApexKycConfig.initialize(
    baseUrl: 'https://api.example.com',
    apiKey: 'your-api-key',
    enableLogging: true,
  );
  
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('KYC Verification')),
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              // Start KYC Flow
              Navigator.push(
                context,
                MaterialPageRoute(
                  builder: (context) => ApexKycFlowWidget(
                    applicantId: 'your-applicant-id',
                    progressStyle: ProgressIndicatorStyle.steps,
                    onComplete: (verification) {
                      Navigator.pop(context);
                      ScaffoldMessenger.of(context).showSnackBar(
                        SnackBar(
                          content: Text('Verification completed!'),
                          backgroundColor: Colors.green,
                        ),
                      );
                    },
                    onError: (error) {
                      Navigator.pop(context);
                      ScaffoldMessenger.of(context).showSnackBar(
                        SnackBar(
                          content: Text('Error: $error'),
                          backgroundColor: Colors.red,
                        ),
                      );
                    },
                  ),
                ),
              );
            },
            child: Text('Start KYC Verification'),
          ),
        ),
      ),
    );
  }
}

Testing Scenarios 🧪 #

The example app includes comprehensive test scenarios:

Scenario 1: Default Configuration #

LivenessDetectionConfig(
  shuffleListWithSmileLast: true,
  startWithInfoScreen: true,
)

Scenario 2: Random Shuffle #

LivenessDetectionConfig(
  shuffleListWithSmileLast: false,
  durationLivenessVerify: 30,
  startWithInfoScreen: false,
)

Scenario 3: Dark Mode + High Resolution #

LivenessDetectionConfig(
  isDarkMode: true,
  cameraResolution: ResolutionPreset.high,
  durationLivenessVerify: 60,
)

Scenario 4: Custom Labels #

LivenessDetectionConfig(
  useCustomizedLabel: true,
  customizedLabel: LivenessDetectionLabelModel(
    blink: 'Kedip 2-3 Kali',
    lookUp: 'Lihat ke Atas',
    smile: 'Tersenyum Lebar',
  ),
)

Scenario 5: Skip Steps (Minimal Challenges) #

LivenessDetectionConfig(
  useCustomizedLabel: true,
  customizedLabel: LivenessDetectionLabelModel(
    blink: 'Blink Eyes',
    lookDown: '', // Skip
    lookLeft: '', // Skip
    lookRight: '', // Skip
    lookUp: 'Look Up Please',
    smile: 'Smile Wide',
  ),
)

Changelog 📝 #

See CHANGELOG.md for complete version history.

API Reference 📚 #

ApexKycConfig #

SDK configuration singleton:

ApexKycConfig.initialize({
  required String baseUrl,
  String? apiKey,
  int timeoutSeconds = 30,
  bool enableLogging = false,
  bool enableManualCapture = true,
  String? companyName,
  String? companyLogoUrl,
});

ApexKycFlowWidget #

Complete KYC verification flow widget:

ApexKycFlowWidget({
  required String applicantId,
  OnSdkKycComplete? onComplete,
  OnSdkKycError? onError,
  bool showProgress = true,
  ProgressIndicatorStyle progressStyle = ProgressIndicatorStyle.linear,
  KycTheme? theme,
  bool showCompanyBranding = false,
  bool showTips = true,
})

FlutterLivenessDetectionRandomizedPlugin #

Liveness detection plugin:

Future<List<LivenessDetectionResult>?> livenessDetection({
  required BuildContext context,
  required LivenessDetectionConfig config,
})

SdkVerificationService #

Backend API service:

final service = SdkVerificationService();

// Create applicant
final applicantId = await service.createApplicant(
  customerIdentifier: 'unique-id',
  email: 'user@example.com',
  fullName: 'John Doe',
);

// Find applicant
final applicantId = await service.findApplicantByIdentifier('identifier-or-email');

// Create verification request
final verification = await service.createVerificationRequest(
  applicantId: applicantId,
  verificationType: VerificationType.passport,
);

// Upload document
final verification = await service.uploadDocument(
  verificationId: verificationId,
  file: imageFile,
  side: 'front', // or 'back'
);

// Get verification status
final verification = await service.getVerification(verificationId);

Troubleshooting 🔍 #

Camera Permission Issues #

Android: Ensure CAMERA permission is declared in AndroidManifest.xml

iOS: Ensure NSCameraUsageDescription is set in Info.plist

Face Detection Not Working #

• Ensure good lighting conditions
• Keep face centered in frame
• Remove glasses or accessories that may obstruct face
• Check camera permissions are granted

Backend Connection Issues #

• Verify baseUrl is correct and accessible
• Check API key is valid (if required)
• Ensure network permissions are granted
• Enable logging to see detailed error messages

Contributing 🤝 #

Contributions are welcome! Please feel free to submit a Pull Request.

License 📄 #

See LICENSE file for details.

Branding Assets 🎨 #

The package includes branding assets located in doc/assets/:

• logo.png - Full logo with icon (523KB)
• logo_without_icon.png - Logo without icon (386KB)
• icon.png - Standalone icon (494KB)

These assets can be used for:

• Documentation and marketing materials
• Company branding in the KYC flow widget
• App icons and splash screens

Using Company Branding in KYC Flow #

ApexKycConfig.initialize(
  baseUrl: 'https://your-backend-api.com',
  companyName: 'Your Company Name',
  companyLogoUrl: 'https://your-cdn.com/logo.png', // Use your hosted logo URL
);

ApexKycFlowWidget(
  showCompanyBranding: true, // Display logo and company name
  // ...
)

Support 💬 #

For issues, questions, or suggestions, please open an issue on GitHub.