JavaScript API

If you wish to use the functionality provided by the Sybrin Document 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.Document.Options({
    // Configuration here
});

var sybrinDocument = new Sybrin.Document.Api();

sybrinDocument.initialize(options);

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

Configuration Options

The following properties are exposed as configuration options:

Optional

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

  • maxUploadFileSize (integer): The maximum size, in bytes, that uploaded files may be. Default 5242880

  • mediaStreamRetryCount (integer): The number of times that the SDK must retry gaining access to the camera if it fails the first time.

  • mediaStreamRetryDelay (integer): The duration that the SDK must wait before retrying gaining access to the camera if it fails the first time.

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

  • takePictureDelay (number): The delay (in milliseconds) before the photo is taken. Default 5000.

  • useCutout (boolean): Sets whether or not the document cutout overlay must be displayed over the video feed. Default true.

  • translations ({ [key: string]: string }): An object literal representing a dictionary lookup that will be used for translating messages and prompts shown by the SDK. Please see the translations section on this page for a list of all translatable text, as well as the localization page for a detailed description on how to implement localization.

Functionality

The Sybrin Identity Javascript API provides multiple ways of running document capture and other functions to control the Web SDK.

These include:

  • Capture Using Camera

  • Capture Using File Upload

  • Cancel

Additionally, the API provides:

  • Set Translations

  • Version Information Retrieval

  • Client Information Retrieval

  • Compatibility Check

  • Get Video Input Devices

Capture Using Camera

To use the camera for capture, you may make use of the captureDocument function exposed by the JavaScript API.

Signature:

captureDocument(params?: { id?: string; element?: HTMLElement; deviceId?: string; }): Promise<DocumentCaptureResult>

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

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

  • element (HTMLElement): The element to create the video feed in. Takes precedence over the id property. Not required if the id property is provided.

Optionally you may also specify the following properties:

  • deviceId (string): ID of the specific device to use for capture.

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:

<div id="video-container"></div>
<button onclick="openCaptureDocument()">Capture Document</button>

The result is of type Sybrin.Document.DocumentCaptureResult and includes the following properties:

  • success (boolean): Whether or not the document was captured successfully.

  • facingMode (string): The facing direction of the camera used during capture.

  • message (string): Additional information when applicable, for instance an error message if one occurred.

  • originalDocumentImage (string): Base64 string of the original photo of the document.

  • croppedDocumentImage (string): Base64 string of the cropped photo of the document (if the document crop component was used).

  • processedDocumentImage (string): Base64 string of the cropped document image after post-processing was applied. This field is populated by the Result component.

Capture Using File Upload

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

Signature:

uploadDocument(params?: { frontFile?: File; frontBase64?: string; loaderContainer?: HTMLElement; }): Promise<DocumentCaptureResult>

An argument may be provided as an object literal to this function call.

Optionally it may specify the following properties:

  • frontFile (File): The front image file. If provided, no file picker will be displayed, and the SDK will instead use the provided image to construct and return a DocumentCaptureResult instance.

  • frontBase64 (string): A base64 string of the front image. If provided, no file picker will be displayed, and the SDK will instead use the provided image to construct and return a DocumentCaptureResult instance.

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

The frontFile and frontBase64 properties offer an opportunity to implement your own method of obtaining files for upload. If none of these are provided, the Web SDK will invoke the default file explorer window provided by the browser to allow for file selection.

If you wish to provide the file, only one parameter between frontFile and frontBase64 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>

Cancel

A function to cancel any action that the document 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 image capture while it's in progress.

Signature:

cancel(): void

Example:

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

Set Translations

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

Signature:

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

Usage example:

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

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

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

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

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

Translations

Currently, no translations are available.

Last updated