JavaScript API

If you wish to use the functionality provided by the Sybrin Biometrics Web SDK but create your own UI entirely, you may achieve this by simply creating an instance of the JavaScript API and using the functions exposed by it.

Initialization

The JavaScript API may be initialized as follows:

var options = new Sybrin.Biometrics.Options({
    apiKey: 'your-api-key-here', 
    authorizationEndpoint: 'your-auth-endpoint-here'
    passiveLivenessEndpoint: 'your-liveness-endpoint-here',
    // modelPath: 'assets' // Use if your model is located elsewhere
});

var biometrics = new Sybrin.Biometrics.Api();

biometrics.initialize(options);

The options object may be used to configure the API as desired.

Configuration Options

The following properties are exposed as configuration options:

Required

• apiKey (string): Your API key as provided by Sybrin.

• authorizationEndpoint (string): The endpoint that will be used to authorize.

• passiveLivenessEndpoint (string): The endpoint that will be used to execute passive liveness detection.

Optional

• assetHeaders (dictionary<string, any>): A dictionary of strings as keys and any value types, used to construct request headers when performing asset retrievals.

• authHeaders (dictionary<string, any>): A dictionary of strings as keys and any value types, used to construct request headers when performing the authorization API call.

• authToken (string): Provides an alternative to the apiKey property. Renders the apiKey property unused and it is thus not required anymore. Only to be used if authentication is being handled externally.

• blurThreshold (number): The threshold that the blur detection algorithm must pass for the image to be considered clear enough. A higher value is more strict. A lower value is less strict. Default 7.0

• debugInfoEndpoint (string): The endpoint that will be used to post debug information to upon using the upload debug info function.

• eyeDetectionThreshold (number): Sets the eye detection sensitivity. Lower values are more relaxed and more likely to return false positives for eye detection, while higher values are stricter. This value has to be a whole number. It is recommended not to go lower than 2 or higher than 5. Default 2.

• faceDistanceLandscapeThreshold (number): The distance threshold in landscape orientation for the face to be considered close enough, where 0.9 is the closest and 0.1 is the furthest. Default 0.5.

• faceDistancePortraitThreshold (number): The distance threshold in portrait orientation for the face to be considered close enough, where 0.9 is the closest and 0.1 is the furthest. Default 0.75.

• integrationApiBaseUrl (string): Sets the base URL for the companion onboarding web API. Only used when useIntegrationApi is set to true.

• mediaStreamStartTimeout (integer): The time (in milliseconds) that the SDK is given to enable and hook onto the user's camera before it times out. The default value is 6000.

• modelPath (string): Path to the model used for UI-side facial detection. The default value is "assets".

• overexposedThreshold (number): The percentage of overexposed pixels that should be present for an image to be considered overexposed. Default 50.

• overexposedValue (number): The grayscale RGB value (0-255) that a pixel's color must be larger than in order to be considered overexposed. Default 220.

• passiveLivenessBodyValues (array of { name: string, value: any }): A collection of names and values, used to construct additional request body items when performing the passive liveness API call.

• passiveLivenessHeaders (dictionary<string, any>): A dictionary of strings as keys and any value types, used to construct request headers when performing the passive liveness API call.

• passiveLivenessModelNumber (string): The version number of the server-side model used for liveness detection. The default value is "7".

• passiveLivenessParamName (string): The parameter name of the image to run passive liveness detection on. The default value is "media".

• recordDebugInfo (string: never | always | onerror | onspoof | onsuccess): Sets whether and when debug info should be recorded for use by download or upload functionality. The default value is "never".

  • never: No debug info is ever recorded.

  • always: Debug info is recorded after every liveness attempt.

  • onerror: Debug info is only recorded when an error occurs.

  • onspoof: Debug info is recorded when a face detection comes back as a spoof.

  • onsuccess: Debug info is only recorded on a successful face detection that is not a spoof.

• targetProcessingSize (number): The target value of the largest dimension that the image will be resized to during preprocessing. Lower values enhance performance but reduce accuracy. Default 640.

• tokenTimeout (number): The duration (in milliseconds) that a token is valid and will be reused for before a new authentication call is made. Default 120000.

• underexposedThreshold (number): The percentage of underexposed pixels that should be present for an image to be considered underexposed. Default 40.

• underexposedValue (number): The grayscale RGB value (0-255) that a pixel's color must be smaller than in order to be considered underexposed. Default 30.

• useIntegrationApi (boolean): Sets whether or not the companion onboarding web API is being used with the web SDK. Renders the authorizationEndpoint and dataExtractionEndpoint properties unused and they are thus not required anymore. integrationApiBaseUrl should also be set when this value is true. Default false.

• videoInterval (integer): The interval (in milliseconds) at which the video stream is analyzed for faces during liveness detection. The default and minimum value is 500.

Component text and localization

• messageAlignment (string): Text prompt to display if a misaligned face is detected. Default "Please center face and open your eyes"

• messageBlurry (string): Text prompt to display when the video feed is too blurred. Default "Image too blurry"

• messageDistance (string): Text prompt to display if the face is too far away. Default "Please move closer to the camera"

• messageIncompatible (string): Text to display in modal that warns the user if the browser is not supported. Default "Browser is not supported."

• messageIncompatibleSafari (string): Text to display in modal that warns the user and prompts them to switch to Safari if the third party browser is not supported on an iOS environment, but Safari might be. Default "Browser is not supported. Please open in Safari."

• messageLightingBright (string): Text prompt to display when the video feed is overexposed. Default "Lighting conditions too bright"

• messageLightingDark (string): Text prompt to display when the video feed is underexposed. Default "Lighting conditions too dark"

• messageNoFace (string): Text prompt to display while no face is detected. Default "Scanning for face..."

• messagePreparing (string): Text prompt to display while initializing the video stream. Default "Preparing..."

• messageSuccess (string): Text prompt to display after a successful image capture. Default "Good job!"

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

• Cancel

Additionally, the API provides:

• Version Information Retrieval

• Client Information Retrieval

• Compatibility Check

• 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.

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

You may also optionally pass 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.

If you wish for the result to also include the image data of the selfie that was analyzed, you may pass the returnImage parameter and set it to true.

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

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().

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.

• image (string): The selfie image that was analyzed, in data URI format (mime type and base64 data). Only returned if the returnImage property was set to true during initialization.

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.

Example:

HTML

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

JavaScript

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

Version Information Retrieval

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

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.

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.

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.

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.

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

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

Get Video Input Devices

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

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.

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.

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.

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');
})