Detailed API Description¶

API Documentation¶

Xcode Quick Help documentation is provided as well as HTML documentation for the SDK.

The Face Liveness SDK Functional Description¶

Constructor¶

Description

Perform initial allocation for the Face Liveness object.

Prototypes

init(frame: CGRect)
init(coder: NSCoder)

Input Parameters

frame: The dimensions and origin of the view.
coder: An instance of NSCoder used to instantiate the view and its properties.

Return Value

A Face Liveness Object.

Throws

This function does not throw any exceptions.

Set Static Property¶

Description

Set the value for a static property to affect all FaceLiveness objects.

Prototypes

public static func setStaticPropertyString(name: StaticPropertyTag, value: String) throws

Input Parameters

property: The property to set. See the StaticPropertyTag enumeration explanation for additional details.
value: The value to assign to the specified property.

Return Value

None

Throws

This function throws an exception.

Set Property¶

Description

Set the value for the specified property.

Prototypes

public func setPropertyString(name: PropertyTag, value: String) throws
public func setPropertyDouble(name: PropertyTag, value: Double) throws
public func setPropertyBool(name: PropertyTag, value: Bool) throws

Input Parameters

property: The property to set. See the PropertyTag enumeration explanation for additional details.
value: The value to assign to the specified property.

Return Value

No return value.

Throws

This function throws an exception.

Layout Subviews¶

Description

Create and set the parent of the FaceLivenessView.

Prototypes

override public func layoutSubviews()

Input Parameters

This function does not take any input parameters.

Return Value

None

Throws

This function does not throw any exceptions.

Get Version¶

Description

Get the SDK version information as a String.

Prototypes

public static String getVersion()

Input Parameters

This function does not take any input parameters.

Return Value

Returns the SDK version as a String

Throws

This function does not throw any exceptions.

Select Workflow¶

Description

Select workflow from a list of workflows: {Alfa, Charlie4, Charlie2, Delay, Echo}

Prototypes

public func selectWorkflow(workflow: String) throws
public func selectWorkflow(workflow: String, overrideParametersJson: String) throws

Input Parameters

workflow: The name of the selected workflow
overrideParametersJson: Parameters used to override specific proerties of a given workflow in Json format.

Return Value

None

Throws

This function throws an exception.

Set Device Position Callback¶

Description

Set callback for device position data retrieval.

Prototypes

public func setDevicePositionCallback(callback: @escaping DevicePositionCallback)

Input Parameters

callback: A callback that is called for device position data retrieval.

Return Value

None

Throws

This function does not throw any exceptions.

Set Feedback Callback¶

Description

Set the callback used for autocapture feedback retrieval.

Prototypes

public func setFeedbackCallback(callback: @escaping FeedbackCallback)

Input Parameters

callback: A callback that is called for autocapture feedback retrieval.

Return Value

None

Throws

This function does not throw any exceptions.

Set Workflow State Callback¶

Description

Set the workflow state callback.

Prototypes

public func setWorkflowStateCallback(callback: @escaping WorkflowStateCallback)

Input Parameters

callback: A callback that is called when the workflow state needs to be retrieved.

Return Value

None

Throws

This function does not throw any exceptions.

Get Region of Interest¶

Description

Retrieve origin i.e. upper left x, y, width, height of the bounding box rect for where the subject’s face is required.

Prototypes

public func getRegionOfInterest() throws -> [CGFloat]

Input Parameters

This function does not take any input parameters.

Return Value

The region of interest as an array containing the x, y, width, and height.

Throws

This function throws an exception.

Start Workflow¶

Description

Start the selected workflow. Workflow State, Autocapture Feedback, and Device Position callbacks, will begin to occur.

Prototypes

public func start() throws

Input Parameters

This function does not take any input parameters.

Return Value

None

Throws

This function throws an exception.

Stop Workflow¶

Description

Stop the currently running workflow.

Prototypes

public func stop() throws

Input Parameters

This function does not take any input parameters.

Return Value

None

Throws

This function throws an exception.

Get Server Package¶

Description

Retrieve the JSON message to send to the Aware Face Liveness Rest Server for additional processing.

Prototypes

public func getServerPackage() throws -> [String : Any]

Input Parameters

This function does not take any input parameters.

Return Value

A JSON message in the form of a dictionary to send to the Aware Face Liveness Rest Server.

Throws

This function throws an exception.

Get Encrypted Server Package¶

Description

Retrieve the encrypted JSON message to send to the Aware Face Liveness Rest Server for additional processing.

Prototypes

public func getEncryptedServerPackage(type: EncryptionType, key: String) throws -> [String: Any]

Input Parameters

type: Selection of which encryption type to use. See the EncryptionType enumeration explanation for additional details.
key: A string containing the encryption public key. The public key is an X.509 certificate in ASN.1, encoded in SubjectPublicKeyInfo format. The header/footer and new line characters are required, and there should be no extra characters in the string.

Return Value

An encrypted JSON message in the form of a dictionary to send to the Aware Face Liveness Rest Server.

Throws

This function throws an exception.

Public Key

Here is an example of creating a public key variable.

var public_key = ""
public_key += "-----BEGIN PUBLIC KEY-----\n"
public_key += "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAl+XiWKgeRRmpv9o/ZbSU\n"
public_key += "Vg8NmPHYQdrm5LNtRvM4wSyD6ELQdh5sPrB6D3q+1O9QeMTUa60Ph6h6UsCZO40D\n"
public_key += "forJmp33mT8EhJ0DfyqcEOVVgcotgr+aLlqfhOeRYYOJoNFuspUvLV+F4hZvFACp\n"
public_key += "EPyy+wxbRKQScJ9ojcHMjI+E0kSYqNAaQZma/IBzNasTCAN25SzXwVR5etD6bsA1\n"
public_key += "OHmunx9zMORWyC9XQhOXwSXD5xfQZMgB0CiZjjmv4TRQPAES388QfI7uiKH67l+3\n"
public_key += "QI1PhWeYa7Niqc7DyfJwqrc//HeIhXejFVEbIq2d7Y9OVjsn92OSy7S4Z9FnFwcV\n"
public_key += "cQIDAQAB\n"
public_key += "-----END PUBLIC KEY-----"

Get Captured Image¶

Description

Retrieve the captured image found with workflow using autocapture on device.

Prototypes

public func getCapturedImage() throws -> UIImage

Input Parameters

This function does not take any input parameters.

Return Value

Returns image if successfully autocaptured.

Throws

This function throws an exception.

Get Recorded Video¶

Description

Retrieve the video recorded during the previous capture session. The video is in MP4 format at 10 FPS maximum. Devices with lower specs may record at a lower FPS. Up to 30 seconds of video can be recorded based on the .maxRecordedVideoLength property being set.

Prototypes

public func getRecordedVideo() throws -> Data

Input Parameters

This function does not take any input parameters.

Return Value

Data containing the bytes for an MP4 recording of the capture session.

Throws

This function can throw a recordedVideoNotAvailable error if there is no video available.

The Face Liveness SDK Public Enumerations¶

Provides information such as facial positioning. See FeedbackResult (Listing 2)

Listing 2 FeedbackResult¶

public class FeedbackResult {
   public var autocaptureFeedback: AutocaptureFeedback
}

StaticPropertyTag - Defines static property. See StaticPropertyTag (StaticPropertyTag Tags)

Listing 3 Command Types¶

@objc public enum StaticPropertyTag: Int {
   case faceModel
}

Table 4 Static Property Tags:¶
Value	Type	Description
Face Model	String	Determines if the application is using the Light Weight Face Model or the High Accuracy Face Model. Valid values are ‘Mobile’ for the Light Weight Face Model and the path to the ‘FaceModelStandardv2.dat’ for the High Accuracy Model.

PropertyTag - Defines the name of property. See PropertyTag (Listing 4)

Listing 4 Property Tags¶

@objc public enum PropertyTag: Int {
    case username
    case constructImage
    case captureTimeout
    case eyeSeparation
    case captureOnDevice
    case checkPhonePosition
        case enableAutocapture
        case maxRecordedVideoLength
}

Table 5 Property Tags:¶
Value	Type	Description
Username	String	Used to set the Username/ID field when communicating with the Face Liveness Server. Default is a blank string.
Construct Image	Boolean	When possible, return a cropped and rotated image from the Face Liveness Server. See the Face Liveness Server manual for JSON response details. Default is False.
Timeout	Double	Duration (in seconds) of attempting facial capture before aborting the Workflow. Set to 0 for no timeout. Default is no timeout.
Eye Separation	Double	Adjusts the minimum eye separation (in pixels) required for on device captures.
Capture On Device	Boolean	Make a 480x640 capture image available via the getCapturedImage method. Default False.
Check Phone Position	Boolean	When enabled, the phone must be held vertically as part of the capture process. When disabled, the phone may be held at any angle during capture. This is enabled by default.
Enable Autocapture	Boolean	When disabled, autocapture will continue even if the subject is ready for capture. Once re-enabled, autocapture will resume and capture once the subject is in the correct position. This is enabled by default.
Max Recorded Video Length	Double	Duration (in seconds) of video to record from the capture process. After successfully recording, the getRecordedVideo function can be used to get the video data for the previous capture. Default is 0 seconds. Maximum allowed 30 seconds.

WorkflowState - State information of workflow progress. See WorkflowState (Listing 5)

Listing 5 Workflow States¶

 @objc public enum WorkflowState: Int {
   case workflowPreparing
   case workflowDeviceInPosition
   case workflowHoldSteady
   case workflowCapturing
   case workflowEvent            - Not currently used
   case workflowShowUI           - Not currently used
   case workflowHideUI           - Not currently used
   case workflowPostProcessing   - Not currently used
   case workflowComplete
   case workflowAborted
   case workflowTimedOut
   case workflowSensorError
 }

Table 6 Workflow States:¶
Value	Description
Preparing	The Workflow is preparing for facial image analysis. Device is not in the correct position.
Device in Position	The Workflow has detected the device is being held in the correct position.
Hold Steady	The Workflow has detected the device and subject are both in the correct position. This is received along with the COMPLIANT AutoFeedback code.
Capturing	The Workflow is collecting final data. Continue to hold device steady with subject in the same position.
Event	Currently unused.
Show UI	Currently unused.
Hide UI	Currently unused.
Post Processing	Currently unused.
Complete	The Workflow is done. The liveness decision can be retrieved via getLivenessDecision.
Aborted	The Workflow has been aborted. Handle the Workflow exiting.
Timedout	The Workflow has timed out. The server package is available via getServerPackage (Knomi S Face SDK).
Sensor Error	The Workflow has stopped due to invalid sensor readings being detected. Check that the device is functioning normally.

AutocaptureFeedback - Feedback from the autocapture algorithm, part of FeedbackResult. See AutocaptureFeedback (Listing 6)

Listing 6 AutocaptureFeedback¶

 @objc public enum AutocaptureFeedback: Int {
   case OFF,
   COMPLIANT_IMAGE,
   NO_FACE_DETECTED,
   MULTIPLE_FACES_DETECTED,
   INVALID_POSE,
   FACE_TOO_FAR,
   FACE_TOO_CLOSE,
   FACE_ON_LEFT,
   FACE_ON_RIGHT,
   FACE_TOO_HIGH,
   FACE_TOO_LOW,
   INSUFFICIENT_LIGHTING,
   LIGHT_TOO_BRIGHT,
   TOO_MUCH_BLUR,
   SMILE_PRESENT,
   FOREHEAD_COVERING,
   BACKGROUND_TOO_BRIGHT,
   BACKGROUND_TOO_DARK,
   LEFT_EYE_CLOSED,
   RIGHT_EYE_CLOSED,
   LEFT_EYE_OBSTRUCTED,
   RIGHT_EYE_OBSTRUCTED,
   HEAVY_FRAMES,
   GLARE,
   DARK_GLASSES,
   FACIAL_SHADOWING,
   UNNATURAL_LIGHTING_COLOR,
   MOUTH_OBSCURED,
   UNKNOWN
   public static func allValues() -> [AutocaptureFeedback]
   public var description: String { get }
   public static func fromString(term: String) -> AutocaptureFeedback
}

Table 7 Subject Feedback:¶
Value	Description
Off	The Workflow was still preparing to perform facial analysis. Wait for next set of feedback.
Compliant Image	The subject was compliant with all checks. The subject and device should maintain current position to finish data collection.
No Face Detected	No face was detected in the current image.
Multiple Faces Detected	Multple faces detected in the image provided.
Invalid Pose	The subject’s facial pose is invalid.
Face Too Far	The subject’s face is too far from the camera. The subject must move closer or move the device closer.
Face Too Close	The subject’s face is too close to the camera. The subject must back up or move the device slightly away.
Face On Left	The subject’s face is too far to the left. The subject must shift right closer towards the center.
Face On Right	The subject’s face is too far to the right. The subject must shift left closer towards the center.
Face Too High	The subject’s face is too high. The subject must shift downwards towards the center.
Face Too Low	The subject’s face is too high. The subject must shift upwards towards the center.
Insufficient Lighting	There is insufficient lighting in the current environment to gather data. The subject needs to relocate to better lighting conditions.
Light Too Bright	There is too much lighting in the current environment to gather data. The subject needs to relocate to better lighting conditions.
Too Much Blur	The camera is out of focus
Smile Present	The subject was detected smiling or with an open mouth. The subject needs to close their mouth and have a neutral expression on their face.
Forehead Covering	The subject was detected as having an obstruction on their forehead. The subject needs to remove the obstruction from their head.
Background Too Bright	The background is too bright.
Background Too Dark	The background is too dark.
Left Eye Closed	The subject was detected as having their left eye closed. The subject needs to open their eye.
Right Eye Closed	The subject was detected as having their right eye closed. The subject needs to open their eye.
Left Eye Obstructed	The subject’s left eye was detected as being obstructed. The subject needs to ensure a clear view of their eye.
Right Eye Obstructed	The subject’s right eye was detected as being obstructed. The subject needs to ensure a clear view of their right eye.
Heavy Frames	The subject was detected as wearing heavy or thick glasses frames. The subject needs to remove their glasses for capture.
Glare	The frame is non-compliant due to excessive glare.
Dark Glasses	The subject was detected as wearing tinted or dark glasses. The subject needs to remove their glasses for capture.
Unnatural Lighting Color	The subject was detected being in unnatural lighting conditions. The subject needs to relocate to better lighting conditions.
Mouth Obscured	The subject was detected as having their mouth obscured. The subject needs to ensure a clear view of their mouth.

EncryptionType - Encryption types for encrypted server packages. See EncryptionType (Listing 7)

Listing 7 Encryption Types¶

 @objc public enum EncryptionType: Int, CustomStringConvertible {
   case RSA_AES_256_CBC
   public var description: String { get }
}

Table 8 Encryption Types:¶
Value	Description
RSA_AES_256_CBC	The encryption type is a symmetric-asymmetric RSA hybrid based on a AES 256-bit cipher block chain.

FaceLivenessError - Error codes for FaceLiveness. See FaceLivenessError (FaceLiveness Error)

Listing 8 FaceLiveness Error¶

@objc public enum FaceLivenessError: Int, Error, CustomStringConvertible {
    case noError
    case workflowInProgress
    case workflowInvalid
    case workflowNotSelected
    case workflowNoneAvailable
    case workflowInconsistent
    case workflowUnableToInitialize
    case serverPackageNotAvailable
    case cameraInvalid
    case audioUnableToInitialize
    case regionOfInterestNotAvailable
    case imageNotAvailable
        case recordedVideoNotAvailable
    case classifierDataFileNotFound
    case emptyUsernameNotAllowed
    case imageCallbackNotSet
    case feedbackCallbackNotSet
    case workflowStateCallbackNotSet
    case propertyInvalid
    case faceModelInvalid
    case faceModelNotSupportWorkflow
    case methodNotAvailable
    case functionNotAvailableInProduct
    case invalidEncryptionInfo
    case couldNotEncryptServerPackage
    case deviceMotionSensorError
    public var description: String { get }
}

Table 9 FaceLiveness Errors:¶
Value	Description
No Error	No error.
Workflow In Progress	Workflow in progress.
Workflow Invalid	Invalid workflow.
Workflow Not Selected	Workflow not selected.
Workflow None Available	No workflows available.
Workflow Unable To Initialize	Unable to initialize workflow.
Workflow Inconsistent	Workflow liveness check inconsistency.
Server Package Not Available	Server package not available.
Camera Invalid	Invalid camera.
Audio Unable To Initialize	Unable to initialize audio.
Image Not Available	Image not available.
Recorded Video Not Available	There is no video recording available.
Region Of Interest NotAvailable	Region of Interest not available.
Classifier Data File Not Found	Classifier data file not found.
Empty Username Not Allowed	Empty username not allowed.
Image Callback Not Set	Image callback not set.
Feedback Callback Not Set	Feedback callback not set.
Workflow State Callback Not Set	Feedback callback not set.
Method Not Available	Method not available.
Property Invalid	Invalid property setting.
Face Model Invalid	Face model file not valid.
Face Model Not Support Workflow	Selected face model not supported for the workflow.
Function Not Available In Product	Function not available in this product.
Invalid Encryption Info	Encryption info not valid.
Could Not Encrypt Server Package	Could not encrypt server package.
Device Motion Sensor Error	A problem was detected with the device motion sensors.