Response Parameters

When the Facial Lite SDK flow completes, it sends a broadcast (Android) or delegate callback (iOS) with the result. The payload structure depends on whether the flow succeeded or failed.

Success Response

On a successful face capture and comparison, the SDK returns a faceRecognition event with the following top-level structure:

Key	Type	Description
type	String	Event identifier. Always "faceRecognition" on success.
payload	Object	Contains the comparison result. See the faceRecognition payload below.

faceRecognition Payload

Key	Type	Description
similarity	Float	Confidence score between the source face and the captured face, ranging from 0.0 (no match) to 1.0 (exact match). A value of 0.6 or higher is the recommended threshold to treat the face as recognized. Tune this threshold based on your security and UX requirements.
image	String (base64)	Base64-encoded image of the face captured from the live camera feed. Use this for display, storage, or downstream verification. The string does not include a data-URI prefix (e.g. data:image/jpeg;base64,).
captureType	"auto" | "manual"	Indicates how the face was captured. "auto" means the SDK detected and captured the face automatically within the auto-capture timeout. "manual" means the auto-capture window expired and the user tapped the capture button to take the photo.

Error Response

When the flow fails, the SDK returns an error payload instead of a faceRecognition result:

Key	Type	Description
error	String	Machine-readable error code. See the error codes table below.
message	String	Human-readable explanation of what went wrong. Useful for logging and displaying to the user.

Error Codes

Error Code	Description	Recommended Action
no_source	The source image provided at initialization is missing, empty, or otherwise invalid. The SDK cannot start the comparison flow.	Verify that a non-empty base64 string is passed as facialImage (Android) or source (iOS) before launching the SDK. Re-encode the image and retry.
model_initialization_failed	The on-device facial recognition model failed to load, typically due to device incompatibility or insufficient resources.	Check that the device meets minimum SDK requirements. If the error persists across devices, log the message and escalate to support.
bitmap_conversion_failed	The SDK could not decode the provided source image into a usable bitmap. The image data may be corrupted or in an unsupported format.	Ensure the source image is a valid JPEG or PNG encoded as base64. Re-encode from the original file and pass the new string to the SDK.
no_face	No face was detected in the source image. The comparison flow cannot run without a reference face to match against.	Ask the user to provide a different source image with a clear, front-facing face. Avoid heavily cropped, obscured, or low-resolution photos.
exception	An unexpected runtime error occurred inside the SDK.	Log the accompanying message, allow the user to retry, and contact support if the error recurs.

Example Responses

Success

{
  "type": "faceRecognition",
  "payload": {
    "similarity": 0.653,
    "image": "<base64 image string>",
    "captureType": "auto"
  }
}

Error

{
  "error": "no_face",
  "message": "No face detected in the provided source image."
}