Android SDK Reference

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

Installation

The SDK ships as two Gradle modules — ilive-core (engine, configuration, results) and ilive-ui (drop-in LivenessActivity). Include whichever you need:

// app/build.gradle.kts
dependencies {
    implementation(project(":ilive-core"))
    implementation(project(":ilive-ui")) // optional — only for the drop-in UI
}

Minimum Android API is 26 (Android 8.0). See the quickstart for full Gradle setup and model asset placement.

Entry points

There are two ways to run a liveness session:

Drop-in UI — LivenessActivity from ilive-ui. Launches a full-screen flow with camera, guidance, challenges, and a result screen. Fastest path to integration.
Custom UI — LivenessEngine from ilive-core. You drive the camera and UI; the engine consumes frames and returns a verdict. Use when you need your own design or camera stack.

Top-level helpers live on the ILive object:

Member	Signature	Purpose
`version`	`const val String`	SDK version string.
`createEngine`	`suspend fun createEngine(context, config = default): LivenessEngine`	Factory for the custom-UI engine.
`isDeviceSupported`	`fun isDeviceSupported(context): DeviceSupportResult`	Checks OS version and camera availability.
`compareFaces`	`fun compareFaces(context, referencePhoto, probePhoto, threshold = 0.45f): MatchResult`	1:1 comparison of two JPEGs.
`compareFaceWithEmbedding`	`fun compareFaceWithEmbedding(context, referenceEmbedding, probePhoto, threshold = 0.45f): MatchResult`	Compare a stored embedding against a new JPEG.

Drop-in UI: `LivenessActivity`

com.ilive.sdk.ui.LivenessActivity is a ComponentActivity. The recommended way to launch it is with LivenessContract, a type-safe ActivityResultContract that returns a sealed LivenessOutcome.

import com.ilive.sdk.ui.LivenessContract
import com.ilive.sdk.ui.LivenessOutcome
 
private val launcher = registerForActivityResult(LivenessContract()) { outcome ->
    when (outcome) {
        is LivenessOutcome.Success   -> handleResult(outcome.result)   // full LivenessResult
        is LivenessOutcome.Error     -> show(outcome.message)
        LivenessOutcome.Cancelled    -> /* user backed out */ Unit
    }
}
 
launcher.launch(
    LivenessContract.Input(
        config = ILiveConfig.Builder().build(),  // optional
        passiveMode = true,
    )
)

LivenessContract.Input fields:

Field	Type	Default	Meaning
`config`	`ILiveConfig?`	`null` (SDK defaults)	Configuration for the session.
`passiveMode`	`Boolean`	`false`	`true` runs without user challenges; `false` runs the challenge sequence.

LivenessOutcome variants:

Variant	When it fires	Payload
`Success(result)`	Activity finished with a verdict.	Full `LivenessResult` Parcelable.
`Cancelled`	User backed out / `RESULT_CANCELED`.	—
`Error(message)`	Activity reported a failure or delivered no result.	Human-readable `String`.

The activity also places the LivenessResult in the result Intent under LivenessActivity.EXTRA_RESULT as a Parcelable extra, and the following lightweight summary extras:

Intent extra	Key constant	Type
Verdict string (`PASS`/`FAIL`/`RETRY`)	`LivenessActivity.VERDICT_KEY`	`String`
Session id	`LivenessActivity.SESSION_ID_KEY`	`String`
Confidence	`LivenessActivity.CONFIDENCE_KEY`	`Float`

Legacy launch path (deprecated)

LivenessActivity.pendingResult is deprecated and will be removed in a future release. Use LivenessContract instead — it is race-safe across activity instances and delivers the result as a Parcelable intent extra.

Pre-existing integrations may still launch the activity with ActivityResultContracts.StartActivityForResult and read the static LivenessActivity.pendingResult holder. This path keeps working for one release cycle:

private val launcher = registerForActivityResult(
    ActivityResultContracts.StartActivityForResult()
) { activityResult ->
    @Suppress("DEPRECATION")
    val result = LivenessActivity.pendingResult
    @Suppress("DEPRECATION")
    LivenessActivity.pendingResult = null
    if (result != null && result.verdict == Verdict.PASS) {
        // result.icaoPhoto, result.faceEmbedding, result.attestation
    }
}
 
launcher.launch(Intent(this, LivenessActivity::class.java).apply {
    putExtra(LivenessActivity.EXTRA_PASSIVE_MODE, true)
})

Custom UI: `LivenessEngine`

com.ilive.sdk.LivenessEngine exposes the full capture pipeline without a bundled UI.

Method	Signature	Notes
Create	`suspend LivenessEngine.create(context, config): LivenessEngine`	Prefer `ILive.createEngine(...)`.
Initialize	`suspend fun initialize()`	Loads on-device models. Call once before `processFrame`.
Process frame	`fun processFrame(bitmap: Bitmap): TrackingResult`	Feed every preview frame. Returns face detection + landmarks.
Start challenges	`fun startChallenges(listener: ChallengeEventListener)`	Kicks off the interactive challenge sequence.
Evaluate (active)	`suspend fun evaluateVerdict(): LivenessResult`	Call after `AllComplete`.
Evaluate (passive)	`suspend fun evaluatePassiveVerdict(): LivenessResult`	Skips challenges; scores purely from captured frames.
Release	`fun release()`	Free resources. Idempotent.
`sessionId`	`String`	UUID for this session.
`currentStage`	`LivenessStage`	`INITIALIZING`, `READY`, `CHALLENGES`, `PROCESSING`, `RESULT`.

val engine = ILive.createEngine(context, config)
engine.initialize()
 
// For each preview Bitmap:
val tracking = engine.processFrame(bitmap)
 
// Passive flow:
val result = engine.evaluatePassiveVerdict()
engine.release()

Configuration: `ILiveConfig`

ILiveConfig is built via ILiveConfig.Builder(). All fields are optional; defaults match the values shipped in the SDK.

Challenges and verdict thresholds

Field	Type	Default	Description
`challengeCount`	`Int` (3–6)	`3`	Number of challenges run in active mode.
`challengeTypes`	`Set<ChallengeType>`	all 8	Pool of challenges to draw from. Must contain at least `challengeCount` entries.
`challengeTimeoutSeconds`	`Int` (4–15)	`8`	Per-challenge timeout.
`transitionDelayMs`	`Int` (300–3000)	`500`	Pause between challenges.
`maxRetriesPerChallenge`	`Int` (0–2)	`1`	In-session retry count for a failed challenge.
`passThreshold`	`Float`	`0.70`	Minimum confidence for `PASS`.
`retryThreshold`	`Float`	`0.45`	Minimum confidence for `RETRY` (must be less than `passThreshold`).
`antispoofFloor`	`Float`	`0.30`	Anti-spoof layer veto floor.
`deepfakeFloor`	`Float`	`0.20`	Deepfake layer veto floor.
`layerWeights`	`LayerWeights`	balanced	Per-layer weight vector. Normalized automatically.

ChallengeType values: BLINK, TURN_LEFT, TURN_RIGHT, NOD, SMILE, MOUTH_OPEN, EYEBROW_RAISE, EYE_FOLLOW.

Voice prompts

Field	Type	Default	Description
`voicePromptsEnabled`	`Boolean`	`false`	Speak challenge instructions.
`voiceRate`	`Float`	`1.0`	Speech rate multiplier.
`voiceLanguage`	`String`	`"en-US"`	BCP-47 locale tag.

Photo extraction

Field	Type	Default	Description
`photoExtractionEnabled`	`Boolean`	`true`	Produce an ICAO-style still on `PASS`.
`photoWidth`	`Int`	`480`	Output width in pixels.
`photoHeight`	`Int`	`600`	Output height in pixels.
`photoJpegQuality`	`Int` (0–100)	`95`	JPEG quality.

Security

Field	Type	Default	Description
`attestationKeyBase64`	`String?`	`null`	Base64-encoded HMAC key used to sign the result payload. Canonical form across all SDKs. When `null`, no attestation is produced.
`attestationKey`	`ByteArray?` (deprecated)	`null`	Deprecated raw-bytes setter, retained for one release. Prefer `attestationKeyBase64`.
`frameBundleEncryptionKey`	`ByteArray?` (exactly 32 bytes)	`null`	AES key used to encrypt the captured frame bundle.
`frameBundleFrameCount`	`Int` (4–16)	`8`	Number of frames included in the encrypted bundle.

Timeouts

Field	Type	Default
`modelLoadTimeoutSeconds`	`Int`	`10`
`cameraInitTimeoutSeconds`	`Int`	`5`
`totalSessionTimeoutSeconds`	`Int`	`120`

val config = ILiveConfig.Builder()
    .challengeCount(4)
    .passThreshold(0.75f)
    .voicePromptsEnabled(true)
    .attestationKeyBase64("MTIzNDU2Nzg5MDEyMzQ1Ng==")
    .build()

Results: `LivenessResult`

Returned by evaluateVerdict() and evaluatePassiveVerdict().

Field	Type	Description
`sessionId`	`String`	UUID assigned when the engine was created.
`verdict`	`Verdict`	`PASS`, `FAIL`, or `RETRY`.
`confidence`	`Float`	Weighted aggregate confidence (0.0–1.0).
`layerScores`	`List<LayerScore>`	Per-layer breakdown (anti-spoof, challenge, face-consistency, deepfake, motion).
`retryHint`	`String?`	User-facing guidance when `verdict == RETRY`.
`failureReason`	`String?`	Diagnostic reason when `verdict == FAIL`.
`icaoPhoto`	`ByteArray?`	JPEG still of the subject, present on `PASS` when photo extraction is enabled.
`photoQualityScore`	`Float?`	Quality rating for `icaoPhoto` (0.0–1.0).
`faceEmbedding`	`FloatArray?`	512-dimensional face embedding from the best frame. Reusable with `compareFaceWithEmbedding`.
`attestation`	`Attestation?`	Signed payload (`payload`, `signature`, `algorithm`) when `attestationKeyBase64` was set.
`encryptedFrameBundle`	`FrameBundle?`	Encrypted captured frames (`ciphertext`, `iv`, `frameCount`, `keyId`) when a frame-bundle key was set.
`metadata`	`SessionMetadata`	Duration, challenge timings, device model, OS version, SDK version.

Face recognition: `ILive.compareFaces()`

One-shot 1:1 face comparison. Loads the face-matching model, runs the comparison, and releases it.

fun compareFaces(
    context: Context,
    referencePhoto: ByteArray,   // JPEG bytes
    probePhoto: ByteArray,       // JPEG bytes
    threshold: Float = 0.45f
): FaceRecognition.MatchResult
 
fun compareFaceWithEmbedding(
    context: Context,
    referenceEmbedding: FloatArray, // 512 floats, e.g. from LivenessResult.faceEmbedding
    probePhoto: ByteArray,
    threshold: Float = 0.45f
): FaceRecognition.MatchResult

MatchResult fields: similarity: Float (cosine similarity, 0.0–1.0), isMatch: Boolean (similarity >= threshold), threshold: Float.

// Compare an ID document photo against the captured liveness photo.
val match = ILive.compareFaces(
    context = this,
    referencePhoto = idDocumentJpeg,
    probePhoto = livenessResult.icaoPhoto!!
)
 
// Later: compare the stored embedding against a new selfie.
val match2 = ILive.compareFaceWithEmbedding(
    context = this,
    referenceEmbedding = livenessResult.faceEmbedding!!,
    probePhoto = newSelfieJpeg
)

Error handling

All SDK-raised exceptions extend com.ilive.sdk.common.ILiveError:

Error	When it fires
`CameraInitFailed`	Camera could not be opened.
`CameraPermissionDenied`	`android.permission.CAMERA` not granted.
`ModelLoadFailed(modelName)`	A model asset failed to load.
`ModelChecksumMismatch(modelName, expected, actual)`	Shipped model asset was tampered with.
`UnknownModel(modelName)`	Model name not recognized.
`InferenceFailed(modelName)`	A model returned an error during processing.
`SessionTimeout(stage)`	Session exceeded the timeout for the given stage.
`NoFaceDetected`	No face found in any captured frame.
`InvalidConfiguration(detail)`	`ILiveConfig.Builder.build()` rejected the configuration.
`EngineNotInitialized`	`processFrame`/`evaluate*` called before `initialize()`.
`EngineAlreadyReleased`	Engine method called after `release()`.
`InternalError(detail)`	Unexpected internal failure.

Android SDK Reference

Android SDK Reference

Installation

Entry points

Drop-in UI: `LivenessActivity`

Legacy launch path (deprecated)

Custom UI: `LivenessEngine`

Configuration: `ILiveConfig`

Challenges and verdict thresholds

Voice prompts

Photo extraction

Security

Timeouts

Results: `LivenessResult`

Face recognition: `ILive.compareFaces()`

Error handling

See also

Android quickstart

REST API reference

Authentication

Liveness overview

On this page