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:

Trigger Capture
Set Translations
Version Information Retrieval
Client Information Retrieval
Compatibility Check
Get Video Input Devices
Debug Information Download
Debug Information Upload
Get Supported Country Codes

Extract Data Using Camera

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

Signature:

openScanDocument(params?: { id?: string; element?: HTMLElement; documentTypeId?: string; documentTypeName?: string; countryCode?: string; correlationId?: string; deviceId?: string; captureMode: number; imageCaptureFormat: 'jpeg'; }): Promise<DocumentScanResult>

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.
captureMode (number): The mode of capture that should be used. The default value is 0 (automatic). Available modes are as follows:
- 0 - automatic: The SDK will automatically try to detect when a document is in position.
- 1 - manual: The SDK will let the user manually click or tap a button to capture. The button will be centered at the bottom of the video element.
- 2 - semiAutomatic: The SDK will wait for the user to click a button to indicate readiness before it tries to run automatic document detection. The button will be centered at the bottom of the video element.
- 3 - externalManual: The SDK will let the user manually click or tap a button to capture, however the button will not be generated by the SDK. It is up to the consuming application to provide this functionality and invoke the triggerCapture function on the JavaScript API when the user clicks the external button.
- 4 - externalSemiAutomatic: The SDK will wait for the user to click a button to indicate readiness before it tries to run automatic document detection, however the button will not be generated by the SDK. It is up to the consuming application to provide this functionality and invoke the triggerCapture function on the JavaScript API when the user clicks the external button.
correlationId (string): Value that is used to associate the result with a specific case.
deviceId (string): ID of the specific device to use for data extraction.
imageCaptureFormat (string: 'jpeg'): Sets the format that the images will be captured in. Defaults to JPEG.

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:

<button onclick="openScanDocument()">Start Data Extraction</button>

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

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

success (boolean): Whether or not data was extracted successfully.
message (string): Result message.
data (object): A dynamic object that contains the extracted document data.
metadata (object): A special property that contains any additional info emitted as metadata as per the value set in the options configuration for metadataPropertyName.
facingMode (string: user | environment | left | right): The direction/orientation of the camera that was used during capture.
images (object): A wrapper object that contains extracted images.
- documentImage (string): Base64 encoded document front image.
- documentBackImage (string): Base64 encoded document back image.
- portraitImage (string): Base64 face portrait image.
device (Sybrin.Identity.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.

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.

Signature:

uploadDocument(params?: { frontFile?: File; frontBase64?: string; backFile?: File; backBase64?: string; documentTypeId?: string; documentTypeName?: string; countryCode?: string; correlationId?: string; loaderContainer?: HTMLElement; uploadModalContainer: HTMLElement }): Promise<DocumentScanResult>

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.
uploadModalContainer (HTMLElement): The HTML element that must contain the upload modal.

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:

<button onclick="uploadDocument()">Upload Document</button>

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

Signature:

cancel(): void

Example:

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

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

Trigger Capture

A function to trigger capture externally when using a capture mode that allows for external input. This applies to 3 (externalManual) and 4 (externalSemiAutomatic). Please see captureMode property under camera data extraction function for more information.

Signature:

triggerCapture(): void

Example:

<button onclick="triggerCapture()">Capture</button>

var triggerCapture = function() {
    identity.triggerCapture();
};

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-i-translation-41': 'Preparing'
});

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>

Usage example:

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.

Signature:

getClientInfo(): Promise<ClientInfo>

Usage example:

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.

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.

Usage example:

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.

Get Video Input Devices

This function returns 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:

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

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

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

Get Supported Country Codes

The SDK provides two functions to retrieve lists of supported country codes, one for a list of Alpha-3 codes and another for a list of Alpha-2 codes.

These functions are:

getCountryAlpha3Codes - Returns an array of 3 character strings.
getCountryAlpha2Codes - Returns an array of 2 character strings.

Signatures:

getCountryAlpha3Codes(): string[]

getCountryAlpha2Codes(): string[]

Usage examples:

var alpha3Codes = identity.getCountryAlpha3Codes();
console.log('Supported Alpha-3 country codes:');
console.log(alpha3Codes);

var alpha2Codes = identity.getCountryAlpha2Codes();
console.log('Supported Alpha-2 country codes:');
console.log(alpha2Codes);

Last updated 5 months ago