Face Capture (React Native) API

Estimated reading: 10 minutes 129 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 480×640 in portrait mode or 640×480 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.

CodeValueDescription
0FACE_COMPLIANTThe subject’s face was compliant.
1NO_FACE_DETECTEDNo faces were detected in the image. The subject’s face must be wholly in frame.
2MULTIPLE_FACES_DETECTEDMultiple faces were detected in the image. The subject must be the only face in frame.
3INVALID_POSEThe subject’s pose is too far off center. The subject should directly face the camera.
4FACE_TOO_FARThe subject’s face is too far away. The subject should move closer to the camera.
5FACE_TOO_CLOSEThe subject’s face is too close. The subject should move away from the camera.
6FACE_ON_LEFTThe subject’s face is too far to the left. The subject should move to the center of the frame.
7FACE_ON_RIGHTThe subject’s face is too far to the right. The subject should move to the center of the frame.
8FACE_TOO_HIGHThe subject’s face is too high. The subject should move down towards the center of the frame.
9FACE_TOO_LOWThe subject’s face is too low. The subject should move up towards the center of the frame.
10INSUFFICIENT_LIGHTINGThere is insufficient lighting. The subject should move to an area with more uniform lighting.
11LEFT_EYE_CLOSEDThe subject’s left eye is closed. The subject should have both eyes open and visible to the camera.
12RIGHT_EYE_CLOSEDThe subject’s right eye is closed. The subject should have both eyes open and visible to the camera.
13DARK_GLASSES_DETECTEDThe subject is wearing dark or tinted glasses. The subject should remove the dark or tinted glasses.

CameraOrientation

The device’s camera orientation.

CodeValueDescription
0PORTRAITPortrait orientation – Camera is held vertically.
1LANDSCAPELandscape orientation – Camera is held horizontally.

CameraPosition

The position of the camera on the device.

CodeValueDescription
0FRONTCamera is on the front of the device. Used for selfie captures.
1BACKCamera 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.

CodeValueDescription
0HIGH_USABILITYRequest focused on high usability when analyzing on the back-end.
1BALANCEDRequest focused on a balance of usability and security when analyzing on the back-end.
2HIGH_SECURITYRequest focused on high security when analyzing on the back-end.

WorkflowProperty

Configurable properties for Workflows.

CodeValueDescription
0USERNAMEA string value used to set the Username/ID fields when communicating with Knomi S Services.
1CAPTURE_TIMEOUTA double value indicating the maximum duration in seconds for attempting face capture before ending the capture session.
2CAPTURE_PROFILEA string value used to set the capture criteria for Face Capture.

EncryptionType

The type of encryption for server packages.

CodeValueDescription
1RSA_AES_256_CBCRSA AES-256 CBC encryption.
CONTENTS