Liveness Web Component
Introduction
The liveness web SDK is a versatile component that allows you to easily handle authentication process in your web application. The purpose of the SDK is to simplify the integration of our clients to the authentication app.
How the SDK works
The main highlights of the SDK are as the following:
The SDK can be easily embedded in any web application as a reusable web component, declared just like any other HTML element. By using the SDK as an embedded component, the entire journey can be handled within your own domain without the need for redirection to a new domain.
With a customised configuration object, you can set up the SDK according to your preferences.
The SDK event broadcast is a useful tool that provides visibility into user activity from the beginning to the end of the journey and allows you to respond to user interactions during the process by implementing a desired event handler.
SDK Integration Guide
Integrating liveness web SDK into your web application is a simple and straightforward process. You can follow the integration steps outlined in the following recipe:
How to initialise the SDK
To initialise the SDK, you can use the LivenessWebSdk.init(config) method, which takes a configuration JSON object as input.
In the config object, you can provide specific values for the properties based on your requirements. Adjust the property names and values accordingly to customise the initialisation of the SDK for your web application.
config (JSON Object): The customised configuration used to initialise the SDK. The schema of the config JSON object is defined as follows:
| Field | Type | Necessity | Default | Description |
|---|---|---|---|---|
| runMode | string | Optional | LIVENESS_CHECK | The mode liveness SDK features are setup based on. The supported modes are: - LIVENESS_CHECK - FACE_CAPTURE - FACE_AUTH - FACE_ENROL |
| params.glassesDetectionEnabled | boolean | Optional | false | Glass detection inclusion in face validation process |
| params.attempts | number | Mandatory If runMode is LIVENESS_CHECK | Indicates the number of attempts for liveness check. | |
| params.livenessThreshold | float | Mandatory If runMode is LIVENESS_CHECK | Threshold for liveness check between 0.0 and 1.0 | |
| params.domain | string | Mandatory If runMode is FACE_AUTH or FACE_ENROL | Domain needed for face authentication /enrolment | |
| params.username | string | Mandatory If runMode is FACE_AUTH | User name needed for face authentication | |
| params.clientId | string | Mandatory If runMode is FACE_AUTH | Client Id needed for face authentication | |
| params.sessionId | string | Mandatory If runMode is FACE_AUTH or FACE_ENROL | Session Id needed for face authentication /enrolment | |
| prompts.instruction | string | Position your face within the oval. | Prompt for positioning the face. | |
| prompts.faceDetected | string | Hold still for verification. | Prompt when a face is detected. | |
| prompts.eyesClosed | string | Please keep your eyes open. | Prompt for keeping eyes open. | |
| prompts.faceNotFound | string | Face not detected. Position your face within the oval. | Prompt when face is not detected. | |
| prompts.faceTooFar | string | Move closer until your face fits within the oval. | Prompt when face is too far from the camera. | |
| prompts.faceTooClose | string | Move back until your face fits within the oval. | Prompt when face is too close to the camera. | |
| prompts.faceCropped | string | Please move your face inside the oval. | Prompt for adjusting the position of the face. | |
| prompts.faceCloseToBorder | string | Position your face within the oval. | Prompt for positioning the face within the oval. | |
| prompts.failedToPredictLandmarks | string | Face not detected. Position your face within the oval. | Prompt when facial landmarks cannot be detected. | |
| prompts.tooManyFaces | string | Please ensure only one face is in the frame. | Prompt when multiple faces are detected. | |
| prompts.faceAngleTooLarge | string | Please look straight at camera. | Prompt for facing the camera directly. | |
| prompts.lowConfidence | string | Hold still for verification. | Prompt when the liveness check confidence level is low. | |
| prompts.glassesWorn | string | Please remove the glasses if you have any. | Prompt for removing glasses. | |
| prompts.faceIsOccluded | string | Please ensure your face is not obstructed. | Prompt for ensuring the face is not obstructed | |
| prompts.landscapeModeDetected | string | Please hold your device in portrait mode. | Prompt for forcing the user to keep device in portrait |
Logging Event Information
As mentioned, the SDK Event broadcast helps provide visibility into user activity from the beginning to the whole journey and allows you to respond to user interactions during the process by implementing a desired event handler in your code.
The "detail" property of each event provides details about that event. The fields of the "detail" property dispatched by the SDK are as follows:
- type: It specifies the main event types triggered during the verification submission process. You can find a full list of event types in the following table.
- body: This is an optional field that provides additional details about the event type. You can find more information about the body structure in the following table.
| Type | Body | Comments |
|---|---|---|
| SESSION_STARTED | ||
| SESSION_COMPLETED | { "image": "string", "croppedImage":"string", "livenessCheck":"string", "livenessScore": number, "additionalResult": any } | - Image and cropped image as base64 string- livenessCheck value is either LIVE or FAKE. |
| CAPTURING_FACE | { "attempt": number } | |
| FACE_DETECTED | { "attempt": number } | |
| PROCESSING_FACE | { "attempt": number } | |
| USER_PROMPTED | { "attempt": number, "name": "string", "message": "string" } | - name and message will be will be prompts field key and value in respect. |
| ERROR | { "attempt": number, "name": "string", "message": "string" } | - Please refer to 'Error Codes' section for more details. |
- Error Codes
| Name | Message |
|---|---|
| BAD_REQUEST | Invalid request. Please check SDK parameters provided. |
| CAMERA_ACCESS_DENIED | Please allow camera access to continue. |
| GENERAL | It looks like something went wrong. Please try again and if the problem still persists please contact your service provider. |
| TIMEOUT | Timeout reached, cannot capture image. |
Mobile and Desktop Browser Support
The liveness web SDK supports the following browsers on different platforms:
- iOS: iOS Safari, Chrome and Firefox.
- Android: Chrome, Samsung Internet browser and Firefox.
- Desktop: Firefox, Chrome and Safari.
Please ensure that the specified browser versions are met for optimal compatibility and functionality with the SDK.
Updated 5 months ago