Functionality

The Sybrin Biometrics Javascript API provides multiple ways of running liveness detection and other functions to control the Web SDK.

These include:

• Run Liveness Using Camera

• Selfie Capture

• Run Face Comparison

• Extract Face from Image

• Cancel

The SDK also provides journey face registration/verification functions:

• Verify Identifier

• Register Face

• Verify Face

Additionally, the API provides:

• Set Translations

• Hide/Show Loader

• Version Information Retrieval

• Client Information Retrieval

• Compatibility Check

• Handle Compatibility Info

• Get Video Input Devices

• Debug Information Download

• Debug Information Upload

Run Liveness Using Camera

To use the camera for passive liveness detection, you may make use of the openPassiveLivenessDetection function exposed by the JavaScript API.

Signature:

openPassiveLivenessDetection(params?: { id?: string; element?: HTMLElement; correlationId?: string; deviceId?: string; faceInfo?: FaceInfo; imageCaptureFormat: 'jpeg'; }): Promise<PassiveLivenessResult>

Optionally, you may provide an object literal as a parameter and specify either id or element as a property. If no element or ID is provided, the Web SDK will temporarily inject a full screen element to display the video feed. If id (type string) or element (type HTMLElement) is provided, the Web SDK will create the video feed inside the provided element or element matching the provided ID.

You may also optionally provided a device ID to invoke a specific camera. Use the SDK's getVideoInputDevices function to retrieve a list of available video input devices and their IDs.

To cater for disabilities, you may optionally provide a faceInfo value. It is of type FaceInfo, which contains a single property (eyeCount, of type number). This will adjust the eye count validation that is executed during passive liveness.

You may also optionally provide a correlationId value to associate the result with a specific case.

The imageCaptureFormat parameter determines the format of the selfie image and will default to JPEG if not provided.

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

HTML

<button onclick="openPassiveLivenessDetection()">Start Liveness Detection</button>

JavaScript

// Option 1: Asynchronous await
var openPassiveLivenessDetection = async function() {
    try {
        var result = await biometrics.openPassiveLivenessDetection();
        
        console.log('Alive: ', result.alive);
        console.log('Confidence: ', result.confidence);
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

// Option 2: Subscription
var openPassiveLivenessDetection = function() {
    biometrics.openPassiveLivenessDetection().then(function(result) {
        console.log('Alive: ', result.alive);
        console.log('Confidence: ', result.confidence);
    }).catch(function(error) {
        console.log('An error occurred: ', error);
    }).finally(function() {
        console.log('Done');
    });
};

The result is of type PassiveLivenessResult and has the following properties:

• alive (boolean): Whether or not passive liveness passed. True means the selfie is of a live person. False means it is a spoof or that liveness could not be established.

• confidence (number): Confidence level that the selfie is of a live person. This is a decimal value between 0 and 1, where 0 means not confident at all and 1 means 100% confident.

• faceDataUri (string): The face that was extracted from the selfie image, in data URI format.

• faceHash (string): The hash calculated on the extracted face image that is used to ensure that the image comes from a trusted source.

• facingMode (string: user | environment | left | right): The direction/orientation of the camera that was used during capture.

• hash (string): The hash calculated on the selfie image that is used to ensure that the image comes from a trusted source.

• image (string): The selfie image that was analyzed, in data URI format (mime type and base64 data).

• video (blob): Blob data of the .webm video that was recorded for analysis. This property is only populated if video recording was enabled using the includeVideo property within the API configuration options.

• videoHash (string): The hash calculated on the selfie video that is used to ensure that the video comes from a trusted source.

• metadata (object): A special property that contains any additional info emitted as metadata as per the value set in the options configuration for metadataPropertyName.

• device (Sybrin.Biometrics.VideoInputDevice): Details about the device that was used for capture. Properties include:

  • deviceId (string): The ID of the physical video device that was used.

  • groupId (string): The group ID of the physical video device that was used.

  • type (string: Camera | Webcam | Device): The classification type of the physical video device that was used.

  • direction (string: Front | Back | Integrated): The facing direction of the physical video device that was used.

  • label (string): User-friendly display name for the physical video device that was used.

  • counter (number): Index of the physical video device in relation to similar device types.

  • deviceTrackInformation (Sybrin.Biometrics.DeviceTrackInformation): Information about the device track relating to the physical device. Properties include:

    • settings (MediaTrackSettings): The internal media track settings as provided by the browser.

    • constraints (MediaTrackConstraints): The internal media track constraints as provided by the browser.

    • capabilities (MediaTrackCapabilities): The internal media track capabilities as provided by the browser.

Selfie Capture

This function is for taking a selfie without running liveness detection.

For this functionality, you may make use of the openSelfieCapture function exposed by the JavaScript API.

Signature:

openSelfieCapture(params?: { id?: string; element?: HTMLElement; deviceId?: string; faceInfo?: FaceInfo; imageCaptureFormat: 'jpeg'; }): Promise<SelfieCaptureResult>

Optionally, you may provide an object literal as a parameter and specify either id or element as a property. If no element or ID is provided, the Web SDK will temporarily inject a full screen element to display the video feed. If id (type string) or element (type HTMLElement) is provided, the Web SDK will create the video feed inside the provided element or element matching the provided ID.

You may also optionally provide a device ID to invoke a specific camera. Use the SDK's getVideoInputDevices function to retrieve a list of available video input devices and their IDs.

To cater for disabilities, you may optionally provide a faceInfo value. It is of type FaceInfo, which contains a single property (eyeCount, of type number). This will adjust the eye count validation that is executed during selfie capture.

The imageCaptureFormat parameter determines the format of the selfie image and will default to JPEG if not provided.

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

HTML

<button onclick="openSelfieCapture()">Open Selfie Capture</button>

JavaScript

// Option 1: Asynchronous await
var openSelfieCapture = async function() {
    try {
        var result = await biometrics.openSelfieCapture();
        
        console.log('Image: ', result.image);
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

// Option 2: Subscription
var openSelfieCapture = function() {
    biometrics.openSelfieCapture().then(function(result) {
        console.log('Image: ', result.image);
    }).catch(function(error) {
        console.log('An error occurred: ', error);
    }).finally(function() {
        console.log('Done');
    });
};

The result is of type SelfieCaptureResult and has the following properties:

• faceDataUri (string): The face that was extracted from the selfie image, in data URI format.

• faceHash (string): The hash calculated on the extracted face image that is used to ensure that the image comes from a trusted source.

• facingMode (string: user | environment | left | right): The direction/orientation of the camera that was used during capture.

• image (string): The selfie image that was analyzed, in data URI format (mime type and base64 data).

• video (blob): Blob data of the .webm video that was recorded for analysis. This property is only populated if video recording was enabled using the includeVideo property within the API configuration options.

• videoHash (string): The hash calculated on the selfie video that is used to ensure that the video comes from a trusted source.

• hash (string): The hash calculated on the image that is used to ensure that the image comes from a trusted source.

• device (Sybrin.Biometrics.VideoInputDevice): Details about the device that was used for capture. Properties include:

  • deviceId (string): The ID of the physical video device that was used.

  • groupId (string): The group ID of the physical video device that was used.

  • type (string: Camera | Webcam | Device): The classification type of the physical video device that was used.

  • direction (string: Front | Back | Integrated): The facing direction of the physical video device that was used.

  • label (string): User-friendly display name for the physical video device that was used.

  • counter (number): Index of the physical video device in relation to similar device types.

  • deviceTrackInformation (Sybrin.Biometrics.DeviceTrackInformation): Information about the device track relating to the physical device. Properties include:

    • settings (MediaTrackSettings): The internal media track settings as provided by the browser.

    • constraints (MediaTrackConstraints): The internal media track constraints as provided by the browser.

    • capabilities (MediaTrackCapabilities): The internal media track capabilities as provided by the browser.

Run Face Comparison

This function is for running face comparison between two images and returning a match rate.

For this functionality, you may use the runFaceComparison function exposed by the JavaScript API.

Signature:

runFaceComparison(params: { face1: FaceCaptureData; face2: FaceCaptureData; correlationId?: string; }): Promise<SelfieCaptureResult>

Both faces must be new instances of the FaceCaptureData class, which can be populated with data acquired from operations done by components such as the Selfie Capture component. Properties are as follows:

• faceDataUri (string): Data URI of extracted/cropped out face image.

• imgDataUri (string): Original selfie image data URI.

• file (Blob): File of a selfie.

• video (Blob): Video of face.

• facingMode (string: user | environment | left | right | file): Device facing mode used.

• hash (string): Hash calculated on the original image.

• videoHash (string): Hash calculated on the video, if present.

• faceHash (string): Hash calculated on the extracted face, if found.

Usage example:

HTML

<button onclick="compareFaces()">Run Face Comparison</button>

JavaScript

var compareFaces = async function() {
    try {
        var face1 = new Sybrin.Biometrics.FaceCaptureData({
            facingMode: 'user',
            imgDataUri: someDataUri // acquire with upload or capture
        });
        
        var face2 = new Sybrin.Biometrics.FaceCaptureData({
            facingMode: 'user',
            imgDataUri: someDataUri // acquire with upload or capture
        });
        
        var result = await biometrics.runFaceComparison({
            face1: face1,
            face2: face2
        });
        
        console.log('Match result: ', result.match);
        console.log('Match rate: ', result.percentage + '%');
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

The result is of type FaceCompareResult and has the following properties:

• match (boolean): Whether or not the faces match.

• confidence (number): Face match confidence rating (between 0 and 1).

• percentage (number): Face match percentage rating (confidence multiplied by 100).

• face1image (string): Face 1 image data URI.

• face1video (Blob): Face 1 video blob.

• facingMode1 (string: user | environment | left | right | file): Face 1 facing mode.

• face2image (string): Face 2 image data URI.

• face2video (Blob): Face 2 video blob.

• facingMode2 (string: user | environment | left | right | file): Face 2 facing mode.

Extract Face from Image

This function will analyze an image, extract a face and return the result as a data URI.

For this functionality, you may use the extractFaceFromImage function exposed by the JavaScript API.

Signature:

extractFaceFromImage(params: { imageDataUri: string; targetFormat: 'jpeg' }): Promise<string>

The imageDataUri parameter may be a data URI or a base 64 string. The targetFormat parameter determines the format of the extracted face image and will default to JPEG if not provided.

Usage example:

HTML

<button onclick="extractFace()">Extract Face</button>

JavaScript

var extractFace = async function() {
    try {
        const faceDataUri = await biometrics.extractFaceFromImage({ 
            image: base64, // Obtain through a capture or upload method
            targetFormat: 'jpeg'
        });
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

The result is a data URI string.

Cancel

A function to cancel any action that the biometrics Web SDK is currently executing. This is useful if you wish to add a cancel button to the UI so that the user may stop liveness detection while it's in progress.

Signature:

cancel(): void

Usage example:

HTML

<button onclick="cancel()">Cancel</button>

JavaScript

var cancel = function() {
    biometrics.cancel();
};

Verify Identifier

This function may be used to verify the existence of an identifier, provided that a backend instance implements this functionality. The verifyIdentifierEndpoint configuration option is used to determine the endpoint.

Signature:

verifyIdentifier(params: { identifier: string; correlationId: string }): Promise<IdentifierVerificationResult>

The identifier parameter is the value that will be verified for existence. The correlation ID field may be used for advanced data synchronization.

Usage example:

HTML

<button onclick="verifyIdentifier()">Verify Identifier</button>

JavaScript

var verifyIdentifier = async function() {
    try {
        const identifier = 'some-identifier';
        const result = await biometrics.verifyIdentifier({ 
            identifier: identifier
        });
        
        console.log('Success: ', result.success);
        console.log('Exists: ', result.exists);
        console.log('Message: ', result.message);
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

The result is of type IdentifierVerificationResult and has the following properties:

• success (boolean): Whether or not verification executed successfully.

• exists (boolean): Whether or not the identifier exists.

• message (string): Message describing the result.

Register Face

This function may be used to register a new face under a specified identifier, provided that a backend instance implements this functionality. The registerFaceEndpoint configuration option is used to determine the endpoint.

Signature:

registerFace(params: { identifier: string; imageDataUri: string; imageHash: string; video: Blob; videoHash: string; facingMode: string; correlationId: string }): Promise<IdentifierVerificationResult>

Input parameters are as follows:

• identifier (string): The identifier that the face will be registered under.

• imageDataUri (string): Selfie image data URI of the face to register.

• imageHash (string): Hash calculated on the selfie image.

• video (Blob): Video selfie of the face to register.

• videoHash (string): Hash calculated on the video selfie.

• facingMode (string: user | environment | left | right): The direction/orientation of the camera that was used during capture.

• correlationId (string): May be used for advanced data synchronization.

Usage example:

HTML

<button onclick="registerFace()">Register Face</button>

JavaScript

var registerFace = async function() {
    try {
        const identifier = 'some-identifier';
        const result = await biometrics.registerFace({ 
            identifier: identifier,
            imageDataUri: imageDataUri, // Obtain through upload or capture
            imageHash: imageHash, // Calculated by the SDK on the image
            video: video, // Obtain through capture,
            videoHash: videoHash, // Calculated by the SDK on the image
            facingMode: facingMode // Obtain from upload method/device
        });
        
        console.log('Success: ', result.success);
        console.log('Message: ', result.message);
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

The result is of type FaceRegistrationResult and has the following properties:

• success (boolean): Whether or not registration executed successfully.

• message (string): Message describing the result.

Verify Face

This function may be used to verify a selfie against an existing face under a specified identifier, provided that a backend instance implements this functionality. The verifyFaceEndpoint configuration option is used to determine the endpoint.

Signature:

verifyFace(params: { identifier: string; imageDataUri: string; imageHash: string; video: Blob; videoHash: string; facingMode: string; correlationId: string }): Promise<IdentifierVerificationResult>

Input parameters are as follows:

• identifier (string): The identifier of the face that must be verified against.

• imageDataUri (string): Selfie image data URI of the face to verify.

• imageHash (string): Hash calculated on the selfie image.

• video (Blob): Video selfie of the face to verify.

• videoHash (string): Hash calculated on the video selfie.

• facingMode (string: user | environment | left | right): The direction/orientation of the camera that was used during capture.

• correlationId (string): May be used for advanced data synchronization.

Usage example:

HTML

<button onclick="verifyFace()">Verify Face</button>

JavaScript

var registerFace = async function() {
    try {
        const identifier = 'some-identifier';
        const result = await biometrics.verifyFace({ 
            identifier: identifier,
            imageDataUri: imageDataUri, // Obtain through upload or capture
            imageHash: imageHash, // Calculated by the SDK on the image
            video: video, // Obtain through capture,
            videoHash: videoHash, // Calculated by the SDK on the image
            facingMode: facingMode // Obtain from upload method/device
        });
        
        console.log('Success: ', result.success);
        console.log('Verified: ', result.verified);
        console.log('Message: ', result.message);
        console.log('Confidence: ', result.confidence);
        console.log('Percentage: ', result.percentage);
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

The result is of type FaceVerificationResult and has the following properties:

• success (boolean): Whether or not verification executed successfully.

• verified (boolean): Whether or not the face is verified to match.

• message (string): Message describing the result.

• confidence (number): Confidence level that the face matches. This is a decimal value between 0 and 1, where 0 means not confident at all and 1 means 100% confident.

• percentage (number): Confidence rating expressed as a percentage (confidence multiplied by 100).

Set Translations

This function may be used to set translations on a JavaScript API level.

Signature:

setTranslations(translations: { [key: string]: string }): void

Usage example:

biometrics.setTranslations({
    'sy-b-translation-23': 'Preparing'
});

Hide/Show Loader

The JavaScript API provides a function to show a loader, and one to hide any active loader. This is useful for displaying a loader while some asynchronous operation completes.

Signatures:

showLoader(loaderContainer?: HTMLElement): void

hideLoader(): void

Usage example:

var loaderElement = document.getElementsByClassName('loader').item(0);

biometrics.showLoader(loaderElement);

someAsyncFunction().then(function() {
    biometrics.hideLoader();
});

Version Information Retrieval

To get all version info regarding the Web SDK and its components, the API exposes a function called getVersionInfo.

Signature:

getVersionInfo(): Promise<any>

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

JavaScript

biometrics.getVersionInfo().then(function(result) {
    console.log(result);
}).catch(function(error) {
    console.log('An error occurred: ', error);
}).finally(function() {
    console.log('Done');
});

The result has the following properties:

• webSdkVersion (string): The semantic version number of the JavaScript web SDK that is currently in use.

Client Information Retrieval

To get all version info regarding the client environment in which the application is currently running, the API exposes a function called getClientInfo.

Signature:

getClientInfo(): Promise<ClientInfo>

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

JavaScript

biometrics.getClientInfo().then(function(result) {
    console.log(result);
}).catch(function(error) {
    console.log('An error occurred: ', error);
}).finally(function() {
    console.log('Done');
});

The result is of type ClientInfo and has the following properties:

• isMobile (boolean): Whether or not the client environment is mobile (tablet or phone).

• isMobileAndroid (boolean): Whether or not the client environment is running Android.

• isMobileBlackberry (boolean): Whether or not the client environment is running Blackberry.

• isIphone (boolean): Whether or not the client environment is running on an iPhone.

• isIpad (boolean): Whether or not the client environment is running on an iPad.

• isIpadPro (boolean): Whether or not the client environment is running on an iPad Pro.

• isIpod (boolean): Whether or not the client environment is running on iPod.

• isMobileIos (boolean): Whether or not the client environment is running iOS.

• isMobileOpera (boolean): Whether or not the client environment is mobile Opera.

• isMobileWindows (boolean): Whether or not the client environment is Windows Mobile.

• isMac (boolean): Whether or not the client environment is running on Mac.

Compatibility Check

This function checks compatibility of the web SDK with the environment in which it is running (device, operating system, browser etc.) and reports back on it.

Signature:

checkCompatibility(handleIncompatibility?: boolean): Promise<CompatibilityInfo>

Optionally, you may pass down true to signal for the web SDK to handle incompatibility internally. This will result in a modal prompt with an appropriate message automatically being shown if the function finds incompatibility with the environment.

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

JavaScript

biometrics.checkCompatibility().then(function(result) {
    console.log(result);
}).catch(function(error) {
    console.log('An error occurred: ', error);
}).finally(function() {
    console.log('Done');
});

The result is of type CompatibilityInfo and has the following properties:

• compatible (boolean): Whether or not the web SDK is compatible with the client environment.

• mediaRecorder (boolean): Whether or not video recording is supported.

• mediaStream (boolean): Whether or not the client environment supports media stream access.

• message (string): An appropriate message that describes the related incompatibility if detected.

Handle Compatibility Info

Creates a modal to display compatibility issues as contained in the CompatibilityInfo instance.

Signature:

handleCompatibilityInfo(info: CompatibilityInfo): void

The info parameter is an instance of CompatibilityInfo, which may be obtained by running the checkCompatibility function on the JavaScript API.

Usage example:

JavaScript

// Obtain info with the checkCompatibility function
biometrics.handleCompatibility(info); 

Get Video Input Devices

This function returns a promise with a list of all video input devices that can be used.

Signature:

getVideoInputDevices(showLoader?: boolean, loaderContainer?: HTMLElement): Promise<VideoInputDevice[]>

The optional showLoader parameter sets whether or not the UI must be blocked with a loader. When used in conjunction with the optional loaderContainer parameter, the specific element will be blocked with a loader.

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

Usage example:

JavaScript

biometrics.getVideoInputDevices().then(function(result) {
    console.log(result);
}).catch(function(error) {
    console.log('An error occurred: ', error);
}).finally(function() {
    console.log('Done');
});

The result is an array of type VideoInputDevice and each instance has the following properties:

• deviceId (string): ID of the device.

• groupId (string): Group that the device belongs to.

• type (string: Camera | Webcam | Device): The type of device.

• direction (string: Front | Back | Integrated): The direction of the device.

• label (string): A short description of the device.

• counter (number): Number indicator for the device. Value is 0 unless there are multiple devices of the same type and direction available.

Debug Information Download

Before using this function, please ensure that the recordDebugInfo configuration option has been set.

Signature:

downloadDebugInfo(): void

This is for debug and diagnostic purposes only and can only be used once debug functionality has been configured. It can be used after a liveness scan to download an HTML file containing information relating to the scan attempt.

Usage example:

biometrics.downloadDebugInfo();

Debug Information Upload

Before using this function, please ensure that the recordDebugInfo configuration option has been set.

Signature:

uploadDebugInfo(): Promise<boolean>

This is for debug and diagnostic purposes only and can only be used once debug functionality has been configured. It can be used after a liveness scan to upload an HTML file containing information relating to the scan attempt. The file is uploaded to the endpoint configured in the debugInfoEndpoint configuration option.

This function sends a POST message to the configured endpoint and the payload is a string on the form body, called debugInfo.

The function returns a promise, so you may choose to use either the asynchronous await pattern or to subscribe to the result using .then(), .catch() and .finally().

IMPORTANT: The HTML file includes the selfie taken during the scan attempt. Please keep the POPI act in mind when making use of this feature. Sybrin accepts no responsibility for any breach of the POPI act should this function be used to upload data to your own custom hosted service.

Usage example:

biometrics.uploadDebugInfo().then(function() {
    console.log('Upload complete');
}).catch(function(error) {
    console.log('An error occurred: ', error);
}).finally(function() {
    console.log('Done');
})