JavaScript API
Last updated
Last updated
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.
The web SDK offers two methods of authorization.
The first, most preferred and most secure method is to implement the authorization step in your backend solution and then provide the token to the front-end web SDK component. This is the Token Method.
The second method is to allow the web SDK to execute authorization from the UI. This is the API Key Method.
Warning: The API Key Method is extremely unsecure and is not recommended for production environments.
Contrary to what the name implies, you will still require an API key for this approach. The only difference is that the web SDK will never directly make use of the API key and will instead only receive a token.
Sybrin will provide you with an orchestration API endpoint, along with a personalized API key (If you have not received this, please contact us).
To use this method:
Excute a POST call to the authorization endpoint provided to you by Sybrin, adding your API key to an apiKey header on the request. The response will include a token (AuthToken property).
Provide the token returned from the API request to your front-end solution.
Set the token on the authToken property of your Sybrin.Document.Options instance.
This method is much simpler, but also much less secure.
To use this approach:
Set the API key provided to you by Sybrin on the apiKey property of your Sybrin.Document.Options instance.
Set the authorization endpoint provided to you by Sybrin on the authEndpoint property of your Sybrin.Document.Options instance.
This is the preferred approach.
Please follow the steps described here. The JavaScript API may then be initialized as follows:
The options object may be used to configure the API as desired.
This approach is not secure and is not recommended for production environments.
Please follow the steps described here. The JavaScript API may then be initialized as follows:
The following properties are exposed as configuration options:
authToken (string)
: Please see the authorization section for details on how to use this property. Not required if the apiKey
and authEndpoint
properties are used.
apiKey (string)
: Your API key as provided by Sybrin. Please see the authorization section for details on how to use this property. Not required if the authToken
property is used.
authEndpoint (string)
: The endpoint that will be used to authorize. Only required when the integrationMode
property is set to 0 (direct).
ocrEndpoint (string)
: The endpoint that will be used to execute OCR.
authBodyCallback (function)
: A callback function that may be used to modify the body of the authorization API call. As parameters, this function provides the body object before modification. The function expects the modified body object to be returned.
authHeadersCallback (function)
: A callback function that may be used to modify the headers of the authorization API call. As parameters, this function provides the headers object before modification. The function expects the modified headers object to be returned.
authHttpMethod (string: GET | POST | PUT)
: Overrides the HTTP method type for the authorization API call.
ocrBodyCallback (function)
: A callback function that may be used to modify the body of the OCR API call. As parameters, this function provides the body object before modification as well as a SnapshotData
object. The function expects the modified body object to be returned.
ocrHeadersCallback (function)
: A callback function that may be used to modify the headers of the OCR API call. As parameters, this function provides the headers object before modification as well as a SnapshotData
object. The function expects the modified headers object to be returned.
ocrHttpMethod (string: GET | POST | PUT)
: Overrides the HTTP method type for the OCR API call.
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.
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
Execute Document OCR
Cancel
Additionally, the API provides:
Set Translations
Version Information Retrieval
Client Information Retrieval
Compatibility Check
Get Video Input Devices
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; countryCode: string; documentTypeName: string; documentTypeId: string; 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.
countryCode (string)
: The country code of the document. Used during capture, in conjunction with document type parameters, to determine page count. May be obtained by using the Country Select component.
documentTypeName (string)
: The document type name of the document. Used during capture, in conjunction with country code parameters, to determine page count. May be obtained by using the Document Select component.
documentTypeId (string)
: The document type ID of the document. Used during capture, in conjunction with country code parameters, to determine page count. May be obtained by using the Document Select component.
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:
The result parameter 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.
originalDocumentImages (string[])
: Base64 string array of the original photos of the document.
documentImage (string[])
: Base64 string array of the processed photos of the document (if the document crop component was used).
correlationId (string)
: The unique identifier used for advanced tracking and backend data synchronization.
countryCode (string)
: The Alpha-3 standard country code of the country that was selected during the journey.
documentType (string)
: The document type name string of the document type that was selected during the journey.
ocrResults (DocumentOcrResult[])
: The array of document OCR result instances representing the data that was read from the images.
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; backFile?: File; backBase64?: string; documentTypeId?: string; documentTypeName?: string; countryCode?: string; loaderContainer?: HTMLElement; }): Promise<DocumentCaptureResult>
An argument may be provided as an object literal to this function call. The object literal must have these required properties:
countryCode (string)
: Not required if documentTypeId
is specified. Used in conjunction with documentTypeName
to determine page count.
documentTypeId (string)
: Not required if both countryCode
and documentTypeName
are provided. Used to determine page count.
documentTypeName (string)
: Not required if documentTypeId
is specified. Used in conjunction with countryCode
to determine page count.
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:
The result parameter 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.
originalDocumentImages (string[])
: Base64 string array of the original photos of the document.
documentImage (string[])
: Base64 string array of the processed photos of the document (if the document crop component was used).
correlationId (string)
: The unique identifier used for advanced tracking and backend data synchronization.
countryCode (string)
: The Alpha-3 standard country code of the country that was selected during the journey.
documentType (string)
: The document type name string of the document type that was selected during the journey.
ocrResults (DocumentOcrResult[])
: The array of document OCR result instances representing the data that was read from the images.
To run OCR on an image, you may make use of the executeDocumentOcr function exposed by the JavaScript API.
Signature:
executeDocumentOcr(params?: { base64s?: string[]; files?: File[]; facingMode?: string; countryCode?: string; documentTypeName?: string; documentTypeId?: string; correlationId?: string }): Promise<DocumentCaptureResult>
An argument, provided as an object literal, is required for this function call. The object literal must have these required properties:
base64s (string[])
: Array of images, in base64 format, to run OCR on. Not required if files
parameter is provided.
files (File[])
: Array of images, in File format, to run OCR on. Not required if base64s
parameter is provided.
countryCode
: The country code of the document. Used during capture, in conjunction with document type parameters, to determine OCR implementation. May be obtained by using the Country Select component. Not required if documentTypeId has been specified.
documentTypeName
: The document type name of the document. Used during capture, in conjunction with country code parameters, to determine OCR implementation. May be obtained by using the Document Select component. Not required if documentTypeId has been specified.
documentTypeId
: The document type ID of the document. Used during capture, in conjunction with country code parameters, to determine OCR implementation. May be obtained by using the Document Select component. Not required if both countryCode and documentTypeName have been specified.
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.
correlationId (string)
: Value that is used to associate the result with a specific case.
facingMode (string: user | environment | left | right)
: The direction/orientation of the camera that was used during 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:
The result parameter is of type Sybrin.Document.DocumentOcrResult
and includes the following properties:
success (boolean)
: Whether or not document OCR ran successfully.
message (string)
: Additional information when applicable, for instance an error message if one occurred.
ocrData (any)
: A structured data object or unstructured string representing the OCR text that was extracted from the image.
images (object)
: Object containing extracted images, if applicable.
portraitImage (string)
: Base64 string of a face portrait image if one was detected and extracted from the document image.
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:
This function may be used to set translations on a JavaScript API level.
Signature:
setTranslations(translations: { [key: string]: string }): void
Usage example:
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:
The result has the following properties:
webSdkVersion (string)
: The semantic version number of the JavaScript web SDK that is currently in use.
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:
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.
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:
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.
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:
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.
Currently, no translations are available.