JavaScript API

If you wish to use the functionality provided by the Sybrin Identity 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.Identity.Options({
    apiKey: 'your-api-key-here', 
    authorizationEndpoint: 'your-auth-endpoint-here'
    dataExtractionEndpoint: 'your-data-extraction-endpoint-here'
});

var identity = new Sybrin.Identity.Api();

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

• dataExtractionEndpoint (string): The endpoint that will be used to execute data extraction.

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.

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

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

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

• videoInterval (number): The interval (in milliseconds) at which document detection should run on the video feed. Default 500.

• extractionBackParamName (string): The parameter name of the back image to run data extraction on.

• extractionFrontParamName (string): The parameter name of the front image to run data extraction on.

• instructionTextPosition (string: top | bottom | topandbottom): Location of the instruction text while the video feed is being processed. The default value is "topandbottom".

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

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

• recordDebugInfo (string: never | always | onerror | 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 data extraction attempt.

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

  • onsuccess: Debug info is only recorded on a successful data extraction.

• samplesPath (string): Path to the samples used for document detection. Default "assets/samples"

• takePictureDelay (number): The delay (in milliseconds) before the photo is taken once a document is detected in frame. Default 5000.

• thresholdAdjustFactor (number): The factor at which to apply the confidence adjustment when it occurs. Default 0.8.

• thresholdAdjustInterval (number): The interval (in milliseconds) at which to adjust the confidence threshold on the current document. Default 10000.

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

Component text and localization

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

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

• messagePrepareBack (string): Text prompt to display while waiting for the user to flip the document over and prepare the back for capture.

  Default "Please flip the document over for rear photo"

• messagePrepareFront (string): Text prompt to display while waiting for the user to prepare the front of a document for capture. Default "Please hold the document up to the camera"

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

Functionality

The Sybrin Identity Javascript API provides multiple ways of running data extraction on identity documents and other functions to control the Web SDK.

These include:

• Extract Data Using Camera

• Extract Data Using File Upload

• Cancel

Additionally, the API provides:

• Version Information Retrieval

• Client Information Retrieval

• Compatibility Check

• Debug Information Download

• Debug Information Upload

Extract Data Using Camera

To use the camera for data extraction, you may make use of the openScanDocument function exposed by the JavaScript API.

An argument, passed as an object literal, is required for this function call. The object literal must have these required properties:

• documentTypeId (string): The ID that points to a unique document type for a specific country. Not required if countryCode and documentTypeName are specified.

• countryCode (string): The country that data extraction should run for. Not required if documentTypeId is specified.

• documentTypeName (string): The document type that data extraction should run for. Not required if documentTypeId is specified.

Optionally you may also specify the following properties:

• id (string): The ID of the element to create the video feed in. The element property takes precedence over the id property.

• element (HTMLElement): The element to create the video feed in. Takes precedence over the id property.

• correlationId (string): Value that is used to associate the result with a specific case.

If no id or element property is passed on the argument, the Web SDK will temporarily inject a full screen element to display the video feed.

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="openScanDocument()">Start Data Extraction</button>

JavaScript

// Option 1: Asynchronous await
var openScanDocument = async function() {
    try {
        var result = await identity.openScanDocument({
            countryCode: 'ZAF',
            documentTypeName: 'passport'
        });
        
        console.log('Success: ', result.success);
        
        for (const property in result.data) {
            console.log('Value of ' + property + ' is ' + result.data[property]);
        }
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

// Option 2: Subscription
var openScanDocument = function() {
    identity.openScanDocument({
        countryCode: 'ZAF',
        documentTypeName: 'passport'
    }).then(function(result) {
        console.log('Success: ', result.success);
        
        for (const property in result.data) {
            console.log('Value of ' + property + ' is ' + result.data[property]);
        }
    }).catch(function(error) {
        console.log('An error occurred: ', error);
    }).finally(function() {
        console.log('Done');
    });
};

Extract Data Using File Upload

To use a file upload for data extraction, you may make use of the uploadDocument function exposed by the JavaScript API.

An argument, passed as an object literal, is required for this function call. The object literal must have these required properties:

• documentTypeId (string): The ID that points to a unique document type for a specific country. Not required if countryCode and documentTypeName are specified.

• countryCode (string): The country that data extraction should run for. Not required if documentTypeId is specified.

• documentTypeName (string): The document type that data extraction should run for. Not required if documentTypeId is specified.

Optionally you may also specify the following properties:

• frontFile (File): The front image file to run data extraction on.

• backFile (File): The back image file to run data extraction on.

• frontBase64 (string): A base64 string of the front image to run data extraction on.

• backBase64 (string): A base64 string of the back image to run data extraction on.

• correlationId (string): Value that is used to associate the result with a specific case.

• loaderContainer (HTMLElement): The HTML element to display a loader inside while processing.

The frontFile, backFile, frontBase64 and backBase64 properties offer an opportunity to implement your own method of obtaining files for upload. If none of these are passed, the Web SDK will invoke the default file explorer window provided by the browser to allow for front (as well as back, if required for the document type) file selection.

If you wish to provide the front file, only one parameter between frontFile and frontBase64 is required.

If you wish to provide the back file where applicable, only one parameter between backFile and backBase64 is required.

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="uploadDocument()">Upload Document</button>

JavaScript

// Option 1: Asynchronous await
var uploadDocument = async function() {
    try {
        var result = await identity.uploadDocument({
            countryCode: 'ZAF',
            documentTypeName: 'passport'
        });
        
        console.log('Success: ', result.success);
        
        for (const property in result.data) {
            console.log('Value of ' + property + ' is ' + result.data[property]);
        }
    } catch (error) {
        console.log('An error occurred: ', error);
    } finally {
        console.log('Done');
    }
};

// Option 2: Subscription
var uploadDocument = function() {
    identity.uploadDocument({
        countryCode: 'ZAF',
        documentTypeName: 'passport'
    }).then(function(result) {
        console.log('Success: ', result.success);
        
        for (const property in result.data) {
            console.log('Value of ' + property + ' is ' + result.data[property]);
        }
    }).catch(function(error) {
        console.log('An error occurred: ', error);
    }).finally(function() {
        console.log('Done');
    });
};

Cancel

A function to cancel any action that the identity 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 data extraction while it's in progress.

Example:

HTML

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

JavaScript

var cancel = function() {
    identity.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

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

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

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

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:

identity.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:

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