Face Capture (React Native) API

Estimated reading: 10 minutes 799 views

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 session
camera_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:

AA is the major version,
BB is the minor version,
CC is the bug fix version,
DD is 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.