face_liveness_verification 0.2.1

Flutter package for real-time face liveness challenges and FaceNet-based identity verification with configurable matching.

face_liveness_verification

A Flutter package for real-time face liveness checks and FaceNet-based identity verification, with configurable challenge flow, enrollment utilities, and a ready-to-use default UI.

Full Documentation (DOCX)

This package also includes the complete Word documentation file:

• face_liveness_check_complete_documentation.docx

Note: pub.dev does not render DOCX inline, but the file is bundled in the published package archive.

1. Package Overview

face_liveness_verification helps you build biometric verification flows where a user must:

1. Prove they are physically present by completing liveness challenges.
2. Generate a FaceNet embedding from a live frame.
3. Match the live embedding against an enrolled template.

The package is designed for onboarding, step-up authentication, attendance, and identity confirmation flows.

2. Features

• Configurable liveness challenge engine with smile, blink, pose, and neutral checks.
• Deterministic liveness state machine with timeouts and failure reasons.
• Built-in FaceNet embedding extraction from bundled TFLite model.
• Enrollment helper for multi-sample template generation.
• Match service that combines liveness and identity verification.
• Pluggable template persistence through FaceTemplateStore.
• Built-in customizable liveness UI widget.
• Similarity utilities for cosine and Euclidean matching.

3. Why Use This Package?

• You need one package for both liveness and matching.
• You want configurable thresholds and challenge flow per use case.
• You need testable interfaces (EmbeddingExtractor and FaceTemplateStore).
• You want default UI but still need custom UI support.

4. Installation

dependencies:
  face_liveness_verification: ^0.2.1

Then run:

flutter pub get

5. Supported Platforms

• Android: supported.
• iOS: supported.
• Web/Desktop: not officially supported by current dependency stack (google_mlkit_face_detection is mobile-focused).

6. Requirements

• Dart SDK: ^3.13.0
• Flutter: >=1.17.0
• Camera permission in host app

7. Dependencies

• flutter (SDK)
• google_mlkit_face_detection: ^0.13.1
• image: ^4.2.0
• tflite_flutter: ^0.12.1

8. Quick Start

final service = FaceLivenessMatchService(
  livenessConfig: const FaceLivenessConfig(),
  matchingConfig: const FaceMatchingConfig(
    metric: FaceSimilarityMetric.euclidean,
    threshold: 1.0,
  ),
  templateStore: InMemoryFaceTemplateStore(),
);

await service.warmUp();

9. Import Instructions

import 'package:face_liveness_verification/face_liveness_verification.dart';

10. Basic Example

final result = await service.verifyWithStoredTemplate(
  faces: detectedFaces,
  imageSize: imageSize,
  imageBytes: cameraFrameBytes,
);

final uiState = FaceLivenessUiState.fromLivenessMatchResult(result);

11. Advanced Example

Custom challenge flow and metric:

final service = FaceLivenessMatchService(
  livenessConfig: const FaceLivenessConfig(
    actions: [
      FaceLivenessAction.smile,
      FaceLivenessAction.blink,
      FaceLivenessAction.turnLeft,
    ],
    challengeTimeout: Duration(seconds: 10),
    totalSessionTimeout: Duration(seconds: 40),
    randomizeActionOrder: false,
  ),
  matchingConfig: const FaceMatchingConfig(
    metric: FaceSimilarityMetric.cosine,
    threshold: 0.86,
  ),
  templateStore: InMemoryFaceTemplateStore(),
);

12. Complete Example App

See the runnable sample app in example/main.dart.

13. API Documentation

All public APIs are exported via:

• lib/face_liveness_verification.dart

Core Services

• FaceLivenessChecker
• LivenessStateMachine
• FaceEmbeddingExtractor
• FaceLivenessMatchService
• FaceEnrollmentService

Data Models

• FaceLivenessResult
• FaceLivenessMatchResult
• FaceMatchResult
• FaceTemplate
• FaceLivenessUiState

Config Models

• FaceLivenessConfig
• FaceMatchingConfig
• FaceVerificationConfig
• FaceLivenessUiConfig

Storage Contracts

• FaceTemplateStore
• InMemoryFaceTemplateStore

Utilities

• FaceSimilarity

Enums

• FaceLivenessAction
• LivenessSessionState
• FaceValidationPhase
• FaceVerificationFailureReason
• FaceSimilarityMetric

Typedefs

• FaceLivenessUiBuilder

14. Documentation for Every Public Class

Public class behavior is fully documented in source code using Dartdoc comments in lib/src/*.dart.

15. Documentation for Every Public Method

Public methods include Dartdoc for input, output, and behavior in normal and error paths.

16. Documentation for Every Extension

This package currently does not expose public extension methods.

17. Documentation for Every Widget

• FaceLivenessDefaultUi: built-in visual experience.
• FaceLivenessUi: wrapper supporting either default UI or custom builder.

18. Documentation for Every Enum

All exported enums are documented in source:

• FaceLivenessAction
• LivenessSessionState
• FaceValidationPhase
• FaceVerificationFailureReason
• FaceSimilarityMetric

19. Documentation for Every Typedef

• FaceLivenessUiBuilder is documented and typed for custom rendering.

20. Architecture Explanation

flowchart TD
    A[Camera Frame + Detected Faces] --> B[FaceLivenessChecker]
    B --> C{Liveness Complete?}
    C -- No --> D[FaceLivenessResult]
    C -- Yes --> E[FaceEmbeddingExtractor]
    E --> F[FaceSimilarity]
    F --> G[FaceMatchResult]
    G --> H[FaceLivenessMatchResult]
    H --> I[FaceLivenessUiState]
    I --> J[FaceLivenessUi]

21. Folder Structure

lib/
  face_liveness_verification.dart
  src/
    embedding_extractor.dart
    face_embedding_extractor.dart
    face_enrollment_service.dart
    face_liveness_action.dart
    face_liveness_checker.dart
    face_liveness_config.dart
    face_liveness_default_ui.dart
    face_liveness_match_result.dart
    face_liveness_match_service.dart
    face_liveness_result.dart
    face_liveness_ui_state.dart
    face_match_result.dart
    face_matching_config.dart
    face_similarity.dart
    face_similarity_metric.dart
    face_template.dart
    face_template_store.dart
    face_validation_phase.dart
    face_verification_config.dart
    face_verification_failure_reason.dart
    in_memory_face_template_store.dart
    liveness_state_machine.dart
assets/models/facenet.tflite
example/main.dart
test/

22. State Management

The package is state-management agnostic.

• Internal challenge state is managed by LivenessStateMachine.
• Integrate with setState, Provider, Riverpod, Bloc, or any preferred architecture in host app.

23. Configuration Guide

Use FaceLivenessConfig to tune liveness strictness and timing. Use FaceMatchingConfig to tune metric and matching threshold. Use FaceLivenessUiConfig to tune default widget styling.

24. Initialization Guide

1. Create FaceLivenessMatchService.
2. Call warmUp once (screen init).
3. Process camera frames and detected faces.
4. Convert results to FaceLivenessUiState.
5. Call dispose when done.

25. Customization Guide

• Customize action order and thresholds in FaceLivenessConfig.
• Replace in-memory storage with secure implementation of FaceTemplateStore.
• Override default widget with FaceLivenessUi.builder.

26. Best Practices

• Calibrate thresholds using real device and user data.
• Use encrypted storage for templates.
• Never log raw embeddings in production.
• Enroll with multiple samples for robust templates.
• Handle each failureReason with user-friendly guidance.

27. Performance Tips

• Call warmUp before first verification.
• Process frames at controlled intervals.
• Reuse service instance per screen/session.
• Avoid unnecessary image conversions in camera pipeline.

28. Error Handling

Check these outputs in results:

• failureReason
• isValidFace
• isLivenessComplete
• isMatchComplete
• shouldRemoveExtraFaces

Use clear UI instructions for each failure state.

29. Common Mistakes

• Using production thresholds without calibration.
• Ignoring multi-face warnings.
• Not adding camera permissions.
• Storing biometric templates without encryption.
• Forgetting to dispose service resources.

30. FAQ

Q: Can I skip liveness during enrollment? A: Yes, enrollFirstTime and enrollAndPersist support requireLiveness: false.

Q: Can I bring my own storage? A: Yes, implement FaceTemplateStore.

Q: Which metric should I use? A: Use either cosine or Euclidean, then calibrate threshold on your own data.

31. Troubleshooting

• No face detected: increase lighting and improve framing.
• Challenge timeout: loosen thresholds or increase timeout durations.
• Repeated mismatch: recalibrate threshold and improve enrollment quality.
• Embedding failure: verify model asset bundling and image validity.

32. Migration Guide

If migrating from previous package naming:

1. Update dependency name to face_liveness_verification.
2. Update import path to package:face_liveness_verification/face_liveness_verification.dart.
3. Replace any old package asset path with packages/face_liveness_verification/assets/models/facenet.tflite.

33. Testing Guide

Run:

flutter analyze
flutter test

Tests include:

• Similarity math correctness.
• Liveness state machine behavior.
• Template JSON validation.
• Enrollment normalization behavior.

34. Example Screenshots

Screenshots not included yet.

Suggested section assets:

• docs/images/liveness_idle.png
• docs/images/liveness_action_prompt.png
• docs/images/verification_success.png
• docs/images/verification_failed.png

35. Contributing Guide

1. Fork repository.
2. Create feature branch.
3. Add tests for new behavior.
4. Run analyze and tests.
5. Open pull request with change summary.

36. Code Style Guide

• Follow package:flutter_lints rules.
• Prefer immutable configuration and result models.
• Keep public APIs documented with Dartdoc comments.
• Maintain backward compatibility for exported APIs.

37. Security Notes

• Face embeddings are sensitive biometric data.
• Use secure storage and platform-level protection.
• Avoid long-term raw image storage unless required by policy.
• Add additional anti-spoof controls for high-security contexts.

38. License

MIT License. See LICENSE.

39. Changelog

See CHANGELOG.md for release details.

40. Roadmap

• Add benchmark guidance and default threshold calibration samples.
• Add optional secure-store implementation examples.
• Add richer example app with full camera integration.
• Expand platform compatibility guidance.

41. Credits

• google_mlkit_face_detection for face detection and landmarks metadata.
• tflite_flutter for on-device model inference.
• image package for preprocessing pipeline.

42. Support Information

• Issues: https://github.com/miralbutani12002-stack/face_liveness_verification/issues
• Repository: https://github.com/miralbutani12002-stack/face_liveness_verification

Platform Permissions

Android (AndroidManifest.xml):

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

iOS (Info.plist):

<key>NSCameraUsageDescription</key>
<string>Camera is required for face liveness verification.</string>

Pre-Publish Checklist

• Run flutter analyze with zero warnings/errors.
• Run flutter test and keep tests green.
• Confirm README, CHANGELOG, and LICENSE are complete.
• Confirm example app runs and demonstrates main APIs.
• Validate with dart pub publish --dry-run.