React Native API¶

FaceCapture¶

Library object that manages all other Face Capture API classes.

Face Capture Create¶

Description: Create a FaceCapture.

Function Definition:

FaceCapture()

Returns: A new FaceCapture object.

Workflow Create¶

Description: Create a Workflow object using a workflow name. The Workflow object will become invalid if the FaceCapture used to create it is destroyed.

Function Definition:

async workflowCreate(workflowName)

WorkflowCreateParameters:¶
Parameter Name	Parameter Type	Description
workflowName	String	Name of the workflow to create

Returns: A new Workflow object.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
UNKNOWN_WORKFLOW - The workflow name specified did not match any of the valid workflow names. Please see the Constants section for the list of valid names.

Get Camera List¶

Description: Get a list of available Camera objects. Use FaceCapture.constants.CameraPositionFront to get all “selfie”/front facing cameras. Use FaceCapture.constants.CameraPositionBack to get all cameras on the back of the device. See the CameraPosition enumeration description for more details.

Function Definition:

async getCameraList(cameraPosition)

getCameraListParameters:¶
Parameter Name	Parameter Type	Description
camera_position	CameraPosition	Position of the cameras on the device

Returns: An array of Cameras for the camera position specified.

Throws:

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: Start a capture session using the specified Workflow and Camera object. While capturing, you cannot modify either object until the capture session ends. A capture session can end via a stopCaptureSession() call, if the capture session timeout expires, if there is a hardware issue, or if it captures successfully.

Function Definition:

startCaptureSession(workflow, camera)

startCaptureSessionParameters:¶
Parameter Name	Parameter Type	Description
workflow	Workflow	Workflow object containing settings for the capture session
camera	Camera	Camera object to be used in the capture session

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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.
NO_CAPTURE_PROFILE - The CAPTURE_PROFILE WorkflowProperty was not specified. A valid CAPTURE_PROFILE must be set.
INVALID_CAPTURE_PROFILE - The CAPTURE_PROFILE WorkflowProperty specified was not profile valid XML.

Stop Capture Session¶

Description: Stop the current capture session. If there is no capture session running, this is a no-op. The next CaptureState will contain the STOPPED CaptureSessionStatus indicating that the session has successfully stopped. The Frame will not be retrievable and the Feedback may be safely ignored from this CaptureState.

Function Definition:

stopCaptureSession()

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.

Get Capture Session State¶

Description: Blocking function that retrieves the capture session state object.

Function Definition:

async getCaptureSessionState()

Returns: A new CaptureState object.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.

Get Server Package¶

Description: Get the JSON server package as a string value. The PackageType can be either FaceCapture.constants.PackageTypeHighUsability, FaceCapture.constants.PackageTypeBalanced, or FaceCapture.constants.PackageTypeHighSecurity. See the PackageType enumeration description for more details.

Function Definition:

getServerPackage(workflow, packageType)

functionParameters:¶
Parameter Name	Parameter Type	Description
workflow	Workflow	Workflow object containing settings for the capture session
packageType	PackageType	Type of JSON request package

Returns: The function returns a promise and if it succeeds it will resolve with a string containing the JSON server package. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.
INVALID_PACKAGE_TYPE - The packageType specified was invalid.

Get Encrypted Server Package¶

Description: Get the encrypted JSON server package as a string value. The EncryptionType can be FaceCapture.constants.EncryptionTypeRSA_AES_256_CBC. The PackageType can be either FaceCapture.constants.PackageTypeHighUsability, FaceCapture.constants.PackageTypeBalanced, or FaceCapture.constants.PackageTypeHighSecurity. See the EncryptionType and PackageType enumeration descriptions for more details.

Function Definition:

getEncryptedServerPackage(encryptionType, encryptionKey, workflow, packageType)

functionParameters:¶
Parameter Name	Parameter Type	Description
encryption_type	EncryptionType	Type of encryption
encryption_key	String	String containing encryption key
workflow_obj	Workflow	Workflow object containing settings for the capture session
package_type	PackageType	Type of JSON request package

Returns: The function returns a promise and if it succeeds it will resolve with a string containing the encrypted JSON server package. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.
INVALID_PACKAGE_TYPE - The PackageType specified was invalid.
INVALID_ENCRYPTION_TYPE - The EncryptionType specified was invalid.
INVALID_ENCRYPTION_PUBLIC_KEY - The encryption_key specified was invalid.

Get Combined Server Package¶

Description: Get the JSON server package as a string value. Each Workflow object used as a parameter must have started a successful capture. (A capture has succeeded when it reaches the COMPLETED status.) This should only be used when performing both passive and active liveness. There must be exactly one passive liveness workflow and at least one active liveness workflow specified. The PackageType can be either FaceCapture.constants.PackageTypeHighUsability, FaceCapture.constants.PackageTypeBalanced, or FaceCapture.constants.PackageTypeHighSecurity. See the PackageType enumeration description for more details.

Function Definition:

getCombinedServerPackage(workflows, packageType)

functionParameters:¶
Parameter Name	Parameter Type	Description
workflows	Workflow[]	Workflow objects containing settings for the capture session
packageType	PackageType	Type of JSON request package

Returns: The function returns a promise and if it succeeds it will resolve with a string containing the JSON server package. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.
INVALID_PACKAGE_TYPE - The packageType specified was invalid.
INVALID_NUMBER_OF_WORKFLOWS - An invalid number of Workflows have been provided.

Get Encrypted Combined Server Package¶

Description: Get the encrypted JSON server package from multiple workflows as a string value. Each Workflow object used as a parameter must have started a successful capture. (A capture has succeeded when it reaches the COMPLETED status.) This should only be used when performing both passive and active liveness. There must be exactly one passive liveness workflow and at least one active liveness workflow specified. The EncryptionType can be FaceCapture.constants.EncryptionTypeRSA_AES_256_CBC. The PackageType can be either FaceCapture.constants.PackageTypeHighUsability, FaceCapture.constants.PackageTypeBalanced, or FaceCapture.constants.PackageTypeHighSecurity. See the EncryptionType and PackageType enumeration descriptions for more details.

Function Definition:

getEncryptedServerPackage(encryptionType, encryptionKey, workflows, packageType)

functionParameters:¶
Parameter Name	Parameter Type	Description
encryption_type	EncryptionType	Type of encryption
encryption_key	String	String containing encryption key
workflows	Workflow[]	Workflow object containing settings for the capture session
package_type	PackageType	Type of JSON request package

Returns: The function returns a promise and if it succeeds it will resolve with a string containing the encrypted JSON server package. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.
INVALID_PACKAGE_TYPE - The PackageType specified was invalid.
INVALID_ENCRYPTION_TYPE - The EncryptionType specified was invalid.
INVALID_ENCRYPTION_PUBLIC_KEY - The encryption_key specified was invalid.
INVALID_NUMBER_OF_WORKFLOWS - An invalid number of Workflows has been provided.

Capture Session Get Capture Region¶

Description: Function that retrieves the region of the image where the face will be captured in the current Capture Session.

Function Definition:

captureSessionGetCaptureRegion()

Returns: The function returns a promise and if it succeeds it will resolve with an array containing the capture region where the face should be placed. The array is four elements long [x, y, width, height]. The x and y values are at the upper left corner. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.

Capture Session Enable Autocapture¶

Description: Enable or disable the autocapture for the capture session. If there is no capture session running, this is a no-op. If the capture session running was started by an active liveness workflow, this is a no-op.

Function Definition:

captureSessionEnableAutocapture(enableAutocapture)

functionParameters:¶
Parameter Name	Parameter Type	Description
enable_autocapture	Boolean	Boolean value to enable or disable autocapture

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
CAPTURE_SESSION_UNAVAILABLE - There are no capture sessions currently running.

Get Version¶

Description: Get the Face Capture SDK version.

Function Definition:

version()

Returns: The function returns a promise which will resolve to a string containing the Face Capture SDK version.

Throws: None

CaptureState¶

The Capture State object provides a snap-shot 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 in order to get a new status update from the capture session.

Destroy Capture State¶

Description: Destroys the CaptureState object. This will free the memory used by the native library. Calling destroy will invalidate this object. Attempting to use any functions with an invalidated CaptureState will result in the INVALID_CAPTURE_STATE error being thrown.

Function Definition:

finalize()

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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: Function that retrieves the capture session’s status from when the Capture State was created.

Function Definition:

getStatus()

Returns: The function returns a promise and if it succeeds it will resolve to a string representation of the capture sesssion status from when the Capture State was created. See the CaptureSessionStatus enumeration descriptions for details. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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 Frame¶

Description: Function that retrieves the preview frame from when the Capture State was created.

Function Definition:

getFrame()

Returns: The function returns a promise and if it succeeds it will resolve to 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. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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: Function that retrieves the subject feedback from when the Capture State was created.

Function Definition:

getFeedback()

Returns: The function returns a promise and if it succeeds it will resolve to a string representation of the AutoCaptureFeedback when the Capture State was created. See the AutoCaptureFeedback enumeration descriptions for more details. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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¶

Workflow object used to store capture session configurations.

Destroy Workflow¶

Description: Destroys the Workflow object. This will free the memory used by the native library. Calling destroy will invalidate this object. Attempting to use any functions with an invalidated Workflow will result in the INVALID_WORKFLOW error being thrown.

Function Definition:

finalize()

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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: Set a string property vlaue for the specified workflow property. Attempting to set a non-string property will result in a WORKFLOW_PROPERTY_TYPE_MISMATCH error being thrown. The WorkflowProperty can be either FaceCapture.constants.WorkflowPropertyUsername or FaceCapture.constants.WorkflowPropertyCaptureProfile. See the WorkflowProperty enumeration descriptions for more details.

Function Definition:

setStringProperty(workflowProperty, value)

functionParameters:¶
Parameter Name	Parameter Type	Description
workflowProperty	WorkflowProperty	Workflow property having its value set
value	String	New value for the specified workflow property

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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: Set a double property value for the specified workflow property. Attempting to set a non-double property will result in a WORKFLOW_PROPERTY_TYPE_MISMATCH error being thrown. The WorkflowProperty can be FaceCapture.constants.WorkflowPropertyCaptureTimeout. See the WorkflowProperty enumeration descriptions for more details.

Function Definition:

setDoubleProperty(workflowProperty, value)

functionParameters:¶
Parameter Name	Parameter Type	Description
workflowProperty	WorkflowProperty	Workflow property having its value set
value	double	New value for the specified workflow property

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

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.

Camera¶

Camera object used to store capture session configurations.

Destroy Camera¶

Description: Destroys the Camera object. This will free the memory used by the native library. Calling destroy will invalidate this object. Attempting to use any functions with an invalidated Camera will result in the INVALID_CAMERA error being thrown.

Function Definition:

finalize()

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
INVALID_CAMERA - The Camera object has been invalidated by destroy() and cannot be used.

Get Name¶

Description: Get the name of the Camera.

Function Definition:

getName()

Returns: The function returns a promise and if it succeeds it will resolve to a string containing the Camera’s name. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
INVALID_CAMERA - The Camera object has been invalidated by destroy() and cannot be used.

Set Orientation¶

Description: Set the orientation of the camera. This will affect how the capture session expects the camera to be oriented. The CameraOrientation can be either FaceCapture.constants.CameraOrientationPortrait or FaceCapture.constants.CameraOrientationLandscape. See the CameraOrientation enumeration descriptions for more details.

Function Definition:

setOrientation(cameraOrientation)

functionParameters:¶
Parameter Name	Parameter Type	Description
cameraOrientation	CameraOrientation	New camera orientation for this camera to be used in capture sessions

Returns: The function returns a promise and if it succeeds it will resolve with no arguments. If it fails, the promise will reject with a single argument which is an object describing the error.

Throws:

NULL_FACE_CAPTURE_OBJ - The FaceCapture object has been invalidated by destroy() and cannot be used.
INVALID_CAMERA - The Camera object has been invalidated by destroy() and cannot be used.
INVALID_CAMERA_ORIENTATION - The orientation specified was not a valid CameraOrientation.
CAMERA_IN_USE - The Camera is currently in use in a capture session and cannot be modified.