Flutter SDK Reference

This page documents the public Dart API of the ilive_flutter plugin: entry points, configuration, result types, and face comparison helpers. For a step-by-step integration walkthrough, see the Flutter quickstart.

The plugin wraps the Android and iOS SDKs through a platform channel and exposes the same surface to Dart.

Installation

# pubspec.yaml
dependencies:
  ilive_flutter:
    path: path/to/ilive_flutter

import 'package:ilive_flutter/ilive_flutter.dart';

The native SDKs must already be linked into your Android (ilive-core / ilive-ui) and iOS (ILiveCore / ILiveUI) host projects. The quickstart walks through platform setup.

Entry points

Two ways to run a liveness session:

1. Drop-in UI — ILive.start(...). Launches the native drop-in activity/view controller and returns a LivenessResult. Fastest path.
2. Custom UI — LivenessEngine.create(...). Exposes platform-channel streams for face tracking and challenge events so you can build your own Flutter UI on top.

Top-level helpers live on the ILive class:

Drop-in UI: ILive.start()

final result = await ILive.start(
  config: const ILiveConfig(challengeCount: 3, passThreshold: 0.75),
);
 
if (result.verdict == Verdict.pass) {
  // result.icaoPhoto, result.faceEmbedding, result.attestation
}

Custom UI: LivenessEngine

Lifecycle: create + initialize

The engine has a two-step lifecycle that matches the native Android / iOS SDKs: create allocates the engine (cheap) and initialize loads the on-device models (heavier). By default the two steps are fused for you.

Shorthand (default — autoInitialize: true):

final engine = await LivenessEngine.create(config: const ILiveConfig());
// Engine is ready to use — models have been loaded.

Explicit (autoInitialize: false) — useful if you want to show a "loading models" indicator while models load:

final engine = await LivenessEngine.create(
  config: const ILiveConfig(),
  autoInitialize: false,
);
 
// Show your own loading UI here…
await engine.initialize();
// …hide it. Engine is now ready to use.

End-to-end custom UI flow

final engine = await LivenessEngine.create(config: const ILiveConfig());
 
engine.faceTrackingUpdates.listen((update) {
  // update.faceDetected, update.confidence, update.faceBounds
});
 
engine.startChallenges().listen((event) {
  // event instances: prompt, progress, pass, fail, allComplete
});
 
final result = await engine.evaluateVerdict();
await engine.dispose();

Configuration: ILiveConfig

ILiveConfig is an immutable Dart value class. All fields are optional named parameters.

Challenges and verdict thresholds

ChallengeType values: blink, turnLeft, turnRight, nod, smile, mouthOpen, eyebrowRaise, eyeFollow.

Voice prompts

Photo extraction

Security

Theming and timeouts

const config = ILiveConfig(
  challengeCount: 4,
  passThreshold: 0.75,
  voicePromptsEnabled: true,
  attestationKeyBase64: 'MTIzNDU2Nzg5MDEyMzQ1Ng==',
);

Results: LivenessResult

SessionMetadata

ChallengeTiming

for (final timing in result.metadata.challengeTimings) {
  print('${timing.type}: ${timing.durationMs} ms (passed=${timing.passed})');
}

Face recognition

// Compare two JPEGs directly.
final match = await ILive.compareFaces(
  referencePhoto: idDocumentBytes,
  probePhoto: result.icaoPhoto!,
);
if (match != null && match.isMatch) {
  // same person; match.similarity ∈ [0, 1]
}
 
// Compare a stored embedding against a new JPEG — faster for repeated checks.
final match2 = await ILive.compareFaceWithEmbedding(
  referenceEmbedding: result.faceEmbedding!,
  probePhoto: newSelfieBytes,
);

FaceMatchResult fields: similarity (double), isMatch (bool), threshold (double).

Error handling

Platform-channel failures surface as PlatformException with the codes defined in ilive_error.dart. The more common path is a successful call with verdict == Verdict.fail and a populated failureReason — for example "No face detected", "Session timeout", or a hard-floor veto from the anti-spoof or deepfake layer.

Camera permission is still handled by the native drop-in UI; for LivenessEngine custom UI, ensure camera permission is granted via permission_handler before starting.

See also