Web SDK - User Guide
This guide explains how to use the Liveness Verification SDK, focusing on the available functions, its parameters, and how to handle the various events triggered by the SDK during the verification process. The SDK works by verifying the liveness of a base64-encoded image.
Summary
To use the SDK:
- Call the performLiveness function, providing your clientSecret and imageBase64.
- Add event listeners for imageLogError, livenessProcessing, and livenessResultReceived to handle different stages of the process.
- The SDK will trigger these events automatically, providing you with feedback about the success or failure of the liveness verification.
Installation
SDK Integration
To integrate the SDK into your project, include the following script in your HTML file:
<script src="https://demo.facia.ai/facia-sdk.js"></script>
After including the SDK file, you can access the SDK methods using the FaciaLivenessSDK global variable. For example, to perform a liveness check, use the following code:
FaciaLivenessSDK.performLiveness(clientSecret, imageBase64);
Make sure to replace clientSecret and imageBase64 with your actual client secret and base64-encoded image data.
Function
performLiveness(clientSecret, imageBase64)
This function initiates the liveness verification process. It accepts several parameters, enabling you to configure the necessary API endpoints.
Parameters
clientSecret (string):
- Your API client secret used for authentication. This is mandatory for all requests made to the liveness verification system.
imageBase64 (string):
- The base64-encoded string of the image that need to be verified for liveness. This is the core input for the verification process.
Custom Events
The SDK triggers various events throughout the liveness verification process. You can listen for these events to receive updates and handle different outcomes.
Event: imageLogError
This event is dispatched when there is an issue with the image or an API request. You can listen for this event to handle errors in your application.
When triggered:
- Invalid or missing parameters.
- API request failure.
Example
document.addEventListener('imageLogError', (event) => {
console.error('Error:', event.detail.message);
});
Event: livenessProcessing
This event is triggered when the liveness verification process has started successfully.
When triggered:
- Once the SDK initiates the liveness verification request and before polling for the result begins.
Example
document.addEventListener('livenessProcessing', () => {
console.log('Liveness verification process started.');
});
Event: livenessResultReceived
This event is dispatched when the liveness verification result is received. You can listen for this event to check whether the liveness verification passed or failed.
When triggered:
- When the liveness verification is completed, either with a pass or fail result.
Details:
- The event’s detail object includes a message field that indicates whether the result is Liveness Passed or Liveness Failed.
- The result data includes information such as the
client_referenceand additional proof if the verification failed.
Example
document.addEventListener('livenessResultReceived', (event) => {
if (event.detail.message === 'Liveness Passed') {
console.log('Liveness verification passed!');
} else {
console.log('Liveness verification failed. Decline Proof: ' + event.detail.proof);
}
});
Example: How to Use the SDK
Here’s an example of how to integrate the SDK into your project. In this example, the SDK will perform liveness verification on a base64-encoded image and provide the result using custom events.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1.0" />
<title>Liveness Verification SDK</title>
<script src="https://demo.facia.ai/facia-sdk.js"></script> // SDK script included here.
<script>
const clientSecret = 'your-client-secret'; // Replace with your actual client secret
let videoStream;
let videoElement = null;
let canvasElement = null;
let getFicaLivenessSDKMethod = FaciaLivenessSDK; // SDK Global variable to access the SDK Methods
// Initialize the camera and start streaming
async function startCamera() {
videoElement = document.createElement('video');
videoElement.setAttribute('autoplay', '');
videoElement.setAttribute('playsinline', ''); // For iOS Safari
videoElement.style.display = 'block';
document.body.appendChild(videoElement);
try {
videoStream = await navigator.mediaDevices.getUserMedia({ video: true });
videoElement.srcObject = videoStream;
} catch (error) {
alert('Error accessing the camera: ' + error.message);
}
}
// Capture image from the camera stream, convert to base64, and trigger liveness verification
function captureImageAndVerifyLiveness() {
// Create a canvas to draw the video frame
canvasElement = document.createElement('canvas');
canvasElement.width = videoElement.videoWidth;
canvasElement.height = videoElement.videoHeight;
const context = canvasElement.getContext('2d');
context.drawImage(videoElement, 0, 0, canvasElement.width, canvasElement.height);
// Convert the canvas image to base64
const imageBase64 = canvasElement.toDataURL('image/jpeg');
// Trigger liveness verification with the captured base64 image
getFicaLivenessSDKMethod.performLiveness(clientSecret, imageBase64);
}
// Listen for errors
document.addEventListener('imageLogError', (event) => {
console.error('Error:', event.detail.message);
});
// Listen for liveness processing
document.addEventListener('livenessProcessing', () => {
console.log('Liveness verification in progress...');
});
// Listen for the liveness result
document.addEventListener('livenessResultReceived', (event) => {
if (event.detail.message === 'Liveness Passed') {
console.log('Liveness verification passed!');
} else {
console.log('Liveness verification failed. Decline Proof: ' + event.detail.proof || 'unknown');
}
});
// Function to stop the camera stream
function stopCamera() {
if (videoStream) {
const tracks = videoStream.getTracks();
tracks.forEach((track) => track.stop());
}
}
// Attach startCamera function to a button click
window.onload = () => {
document.getElementById('start-camera-btn').addEventListener('click', startCamera);
document.getElementById('capture-image-btn').addEventListener('click', captureImageAndVerifyLiveness);
document.getElementById('stop-camera-btn').addEventListener('click', stopCamera);
};
</script>
</head>
<body>
<h1>Liveness Verification SDK</h1>
<button id="start-camera-btn">Open Camera</button>
<button id="capture-image-btn">Capture Image and Verify Liveness</button>
<button id="stop-camera-btn">Stop Camera</button>
</body>
</html>