Face Capture (React Native) API
FaceCapture Creation
Description: This function generates a new FaceCapture object.
Definition: FaceCapture()
Returns: A newly created FaceCapture object.
Workflow Creation
Description: This function creates a Workflow object using a specified workflow name. The created Workflow object will become invalid if the FaceCapture object used to create it is destroyed.
Definition: async workflowCreate(workflow_name)
Parameters:
workflow_name: Name of the workflow to create
Returns: A new Workflow object.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.UNKNOWN_WORKFLOW: The workflow name provided did not match any valid workflow names.
Getting Camera List
Description: This function fetches a list of available Camera objects. Use CameraPosition.FRONT to fetch all front-facing cameras. Use CameraPosition.BACK to fetch all rear-facing cameras.
Definition: async getCameraList(camera_position)
Parameters:
camera_position: Position of the cameras on the device
Returns: An array of Cameras for the camera position specified.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_CAMERA_POSITION: The position value specified was not a valid CameraPosition.
Start Capture Session
Description: This function starts a capture session using the specified Workflow and Camera objects. The objects can't be modified during an active session.
Definition: async startCaptureSession(workflow_obj, camera_obj)
Parameters:
workflow_obj: Workflow object containing settings for the capture sessioncamera_obj: Camera object to be used in the capture session
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW: The Workflow object has been invalidated by destroy() and cannot be used.INVALID_CAMERA: The Camera object has been invalidated by destroy() and cannot be used.
Stop Capture Session
Description: This function is used to stop the ongoing capture session. If there is no active session, the function will simply not do anything. The capture state's next status will be "STOPPED", indicating the end of the session. No frame can be retrieved after stopping the session, and feedback from this capture state can be ignored.
Definition: stopCaptureSession()
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: If the FaceCapture object has been invalidated by destroy() and can't be used.
Get Capture Session State
Description: This function retrieves the state of the capture session.
Definition: getCaptureSessionState()
Returns: A new CaptureState object.
Exceptions:
NULL_FACE_CAPTURE_OBJ: If the FaceCapture object has been invalidated by destroy() and can't be used.
Get Server Package
Description: This function retrieves the JSON server package as a string value.
Definition: getServerPackage(workflow_obj, package_type)
Parameters:
workflow_obj: Workflow object containing settings for the capture session.package_type: Type of JSON request package.
Returns: The string representation of the JSON server package.
Exceptions:
NULL_FACE_CAPTURE_OBJ: If the FaceCapture object has been invalidated by destroy() and can't be used.CAPTURE_SESSION_UNAVAILABLE: If there are no capture sessions currently running.INVALID_PACKAGE_TYPE: If the package_type specified was invalid.
Get Encrypted Server Package
Description: This function retrieves the encrypted JSON server package as a string value.
Definition: getEncryptedServerPackage(encryption_type, encryption_key, workflow_obj, package_type)
Parameters:
encryption_type: Type of encryption.encryption_key: String containing encryption key.workflow_obj: Workflow object containing settings for the capture session.package_type: Type of JSON request package.
Returns: The string representation of the encrypted JSON server package.
Exceptions:
NULL_FACE_CAPTURE_OBJ: If the FaceCapture object has been invalidated by destroy() and can't be used.CAPTURE_SESSION_UNAVAILABLE: If there are no capture sessions currently running.INVALID_PACKAGE_TYPE: If the package_type specified was invalid.INVALID_ENCRYPTION_TYPE: If the encryption_type specified was invalid.INVALID_ENCRYPTION_PUBLIC_KEY: If the encryption_key specified was invalid.
Capture Session Get Capture Region
Description: This function retrieves the region of the image where the face will be captured in the current Capture Session.
Definition: async captureSessionGetCaptureRegion()
Returns: An array specifying the region of interest, represented as [x, y, width, height]. The x and y values are located at the upper left corner of the region.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.CAPTURE_SESSION_UNAVAILABLE: No capture sessions are currently running.
Capture Session Enable Autocapture
Description: This function enables or disables the autocapture feature for the current capture session.
Definition: async captureSessionEnableAutocapture(enable_autocapture)
Parameters:
enable_autocapture: Boolean value indicating whether to enable (true) or disable (false) autocapture.
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.CAPTURE_SESSION_UNAVAILABLE: No capture sessions are currently running.
Get Version
Description: This function retrieves the Face Capture SDK version as an integer.
Definition: async getVersion()
Returns: An integer representing the Face Capture SDK version in AABBCCDD format where:
AAis the major version,BBis the minor version,CCis the bug fix version,DDis the build version.
Exceptions: None.
Get Version String
Description: This function retrieves the Face Capture SDK version as a string.
Definition: async getVersionString()
Returns: A string representing the Face Capture SDK version.
Exceptions: None.
CaptureState
Description: The Capture State object provides a snapshot of the capture session's state when created. The data provided by a single Capture State will never change. A new Capture State must be retrieved to get a new status update from the capture session.
Destroy Capture State
Description: Destroys the CaptureState object, freeing the memory used by the native library. Once destroy() is called, the object is invalidated and can no longer be used.
Definition: async destroy()
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_CAPTURE_STATE: The CaptureState object has been invalidated by destroy() and cannot be used.
Get Status
Description: Retrieves the capture session's status from when the Capture State was created.
Definition: async getStatus()
Returns: The capture session status from when the Capture State was created. See the CaptureSessionStatus enumeration descriptions for details.
Exceptions: None stated in the original documentation.
Get Frame
Description: Retrieves the preview frame from when the Capture State was created.
Definition: async getFrame()
Returns: A Base64 encoded string containing a preview frame from the capture session. The frame is in JPG format. The frame is either 480x640 in portrait mode or 640x480 in landscape mode.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_CAPTURE_STATE: The CaptureState object has been invalidated by destroy() and cannot be used.NO_FRAME_AVAILABLE: The capture session ended before the next frame was ready. There is no frame available for this Capture State.
Get Feedback
Description: Retrieves the subject feedback from when the Capture State was created.
Definition: async getFeedback()
Returns: The most recent AutoCaptureFeedback update when the Capture State was created. See the AutoCaptureFeedback enumeration descriptions for more details.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_CAPTURE_STATE: The CaptureState object has been invalidated by destroy() and cannot be used.
Workflow
Description: The Workflow object is used to store capture session configurations.
Destroy Workflow
Description: This function destroys the Workflow object, freeing the memory used by the native library. Once destroy() is called, the object is invalidated and can no longer be used.
Definition: async destroy()
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW: The Workflow object has been invalidated by destroy() and cannot be used.
Set Property String
Description: This function sets a string property value for the specified workflow property. If an attempt is made to set a non-string property, a WORKFLOW_PROPERTY_TYPE_MISMATCH error will be thrown.
Definition: async setStringProperty(property, value)
Parameters:
property: Workflow property to be set.value: New value for the specified workflow property.
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW: The Workflow object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW_PROPERTY: The property value was not a valid WorkflowProperty.WORKFLOW_PROPERTY_TYPE_MISMATCH: The property value specified does not accept a String value.
Set Property Double
Description: This function sets a double property value for the specified workflow property. If an attempt is made to set a non-double property, a WORKFLOW_PROPERTY_TYPE_MISMATCH error will be thrown.
Definition: async setDoubleProperty(property, value)
Parameters:
property: Workflow property to be set.value: New value for the specified workflow property.
Returns: None.
Exceptions:
NULL_FACE_CAPTURE_OBJ: The FaceCapture object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW: The Workflow object has been invalidated by destroy() and cannot be used.INVALID_WORKFLOW_PROPERTY: The property value was not a valid WorkflowProperty.WORKFLOW_PROPERTY_TYPE_MISMATCH: The property value specified does not accept a double value.
Enumerations
AutoCaptureFeedback
Feedback provided during a capture session indicating any facial quality issues with the subject.
| Code | Value | Description |
|---|---|---|
| 0 | FACE_COMPLIANT | The subject’s face was compliant. |
| 1 | NO_FACE_DETECTED | No faces were detected in the image. The subject’s face must be wholly in frame. |
| 2 | MULTIPLE_FACES_DETECTED | Multiple faces were detected in the image. The subject must be the only face in frame. |
| 3 | INVALID_POSE | The subject’s pose is too far off center. The subject should directly face the camera. |
| 4 | FACE_TOO_FAR | The subject’s face is too far away. The subject should move closer to the camera. |
| 5 | FACE_TOO_CLOSE | The subject’s face is too close. The subject should move away from the camera. |
| 6 | FACE_ON_LEFT | The subject’s face is too far to the left. The subject should move to the center of the frame. |
| 7 | FACE_ON_RIGHT | The subject’s face is too far to the right. The subject should move to the center of the frame. |
| 8 | FACE_TOO_HIGH | The subject’s face is too high. The subject should move down towards the center of the frame. |
| 9 | FACE_TOO_LOW | The subject’s face is too low. The subject should move up towards the center of the frame. |
| 10 | INSUFFICIENT_LIGHTING | There is insufficient lighting. The subject should move to an area with more uniform lighting. |
| 11 | LEFT_EYE_CLOSED | The subject’s left eye is closed. The subject should have both eyes open and visible to the camera. |
| 12 | RIGHT_EYE_CLOSED | The subject’s right eye is closed. The subject should have both eyes open and visible to the camera. |
| 13 | DARK_GLASSES_DETECTED | The subject is wearing dark or tinted glasses. The subject should remove the dark or tinted glasses. |
CameraOrientation
The device’s camera orientation.
| Code | Value | Description |
|---|---|---|
| 0 | PORTRAIT | Portrait orientation - Camera is held vertically. |
| 1 | LANDSCAPE | Landscape orientation - Camera is held horizontally. |
CameraPosition
The position of the camera on the device.
| Code | Value | Description |
|---|---|---|
| 0 | FRONT | Camera is on the front of the device. Used for selfie captures. |
| 1 | BACK | Camera is on the back of the device. Used for capturing other subjects. |
PackageType
The type of JSON request package to send to the Face Liveness back-end.
| Code | Value | Description |
|---|---|---|
| 0 | HIGH_USABILITY | Request focused on high usability when analyzing on the back-end. |
| 1 | BALANCED | Request focused on a balance of usability and security when analyzing on the back-end. |
| 2 | HIGH_SECURITY | Request focused on high security when analyzing on the back-end. |
WorkflowProperty
Configurable properties for Workflows.
| Code | Value | Description |
|---|---|---|
| 0 | USERNAME | A string value used to set the Username/ID fields when communicating with Knomi S Services. |
| 1 | CAPTURE_TIMEOUT | A double value indicating the maximum duration in seconds for attempting face capture before ending the capture session. |
| 2 | CAPTURE_PROFILE | A string value used to set the capture criteria for Face Capture. |
EncryptionType
The type of encryption for server packages.
| Code | Value | Description |
|---|---|---|
| 1 | RSA_AES_256_CBC | RSA AES-256 CBC encryption. |