Document Scan

This component can be found under the Sybrin.Identity namespace and is called DocumentScanComponent.

Full name: Sybrin.Identity.DocumentScanComponent.

It is a component that wraps the identity data extraction detection functionality provided by the Sybrin Identity JavaScript API and presents it in the form of a simple UI. It's recommended that you use this component if you do not wish to create your own UI and simply want to use the identity data extraction functionality provided by the Sybrin Identity Web SDK.

With default styling, the document scan component appears as follows:

Upon clicking "Start", the user will be prompted with instructions on how to take a viable image for document extraction. Upon proceeding, the user's camera will initialize and the component will display a video feed while the user centers their document inside the rectangle. This action can be cancelled, resulting in the onScanCancelled event firing. Alternatively, the user may click on the text link to upload a photo instead. This will result in a file browser window appearing and will allow the user to select a file.

If an error occurs, the onScanError event will fire.

If liveness detection completes, the onScanResult event will fire.

Initialization

The document scan component can be initialized using the following

code:

<div id='document-scan'></div>

var options = new Sybrin.Identity.Options({
    apiKey: 'your-api-key-here', 
    authorizationEndpoint: 'your-auth-endpoint-here'
    dataExtractionEndpoint: 'your-data-extraction-endpoint-here'
});

// Option 1: Passing an id
var component = new Sybrin.Identity.DocumentScanComponent({ 
    id: 'document-scan',
    options: options,
    countryCode: 'ZAF',
    documentTypeName: 'passport'
});

// Option 2: Passing a DOM element
var element = document.getElementById('document-scan');
var component = new Sybrin.Identity.DocumentScanComponent({ 
    element: element,
    options: options,
    countryCode: 'ZAF',
    documentTypeName: 'passport'
});

component.initialize();

The Sybrin Web SDK provides the option to either pass down the ID of the element you wish to use for component initialization, or to pass the element directly.

Please note that 'document-scan' is just an example in this context and the ID may be changed as desired as long as it matches the value passed down during component initialization in JavaScript.

During initialization, the document scan component allows for a number of configuration options that may be passed down using an object literal. The parameters that may be used on the object include the following:

Required:

id (string): ID of the element you wish to use for component initialization. Not required if element is passed.
element (HTMLElement): Element you wish to use for component initialization. Not required if id is passed.
api (Sybrin.Identity.API): Instance of a JavaScript API that may be pre-configured as desired. Not required if an instance of options is passed.
options (Sybrin.Identity.Options): Configuration options to instantiate Sybrin.Identity.Api with. Not required if an instance of api is passed.
documentTypeId (string): An ID that points to a unique document type for a specific country. Not required if countryCode and documentTypeName are specified.
countryCode (string): The Alpha-3 standard country code of the document to be scanned. Not required if documentTypeId is passed.
documentTypeName (string): The document type to be scanned. Please see document type overrides and filtering for a list of supported document type names. Not required if documentTypeId is passed.

Optional:

correlationId (string): Unique identifier for the case that will be passed down to the back-end if set.
useModal (boolean): Whether or not to pop the video feed out into a modal. By default, this is true.

For altering component text or implementing localization if required:

headingText (string): Text to display in the heading. This will default to the title of the selected document type, or simply "Document" if a selected document title could not be found.
subtitleText (string): Text to display in the subtitle. Default "Take a photo"
startButtonText (string): Text to display in the start button. Default "Start"
gotitButtonText (string): Text to display in the proceed button of the instructions screen. Default "Got it!"
cancelButtonText (string): Text to display in the cancel button. Default "Cancel"
uploadPhotoText (string): Text to display in the upload photo link. Default "or upload photo"
companyText (string): Company text to display at the foot of the component. Default "Sybrin"
lightingInstructionText (string): Instruction text stating to ensure proper lighting conditions. Default "Ensure good lighting"
alignmentInstructionText (string): Instruction text stating to ensure correct alignment. Default "Ensure correct document alignment"
backgroundInstructionText (string): Instruction text stating to ensure that the background is correct. Default "Try to avoid white surface background"

Warning: Initialization will fail if the intended host element does not exist yet.

Always ensure that the initialize function is only called after the DOM is loaded.

Destruction

The document scan component may be removed from the UI by calling the destroy() function on it.

Example:

component.destroy();

Events

The document scan component offers multiple events. To hook onto an event, simply assign a function to it.

The following options are available:

onScanResult(result: DocumentScanResult)
onScanError(error: string)
onScanCancelled()
onBeforeScan()
onBeforeUpload()

On Scan Result

This function is called when a scan result is acquired without error. To hook onto the event, you may use the following code:

component.onScanResult = function(result) {
    console.log('Success: ', result.success);
    for (const property in result.data) {
        console.log('Value of ' + property + ' is ' + result.data[property]);
    }
}

The result parameter is of type Sybrin.Identity.DocumentScanResult and includes the following properties:

success (boolean): Whether or not data could be extracted.
message (string): Additional information when applicable, for instance an error message if one occurred.
data (object): An object with all data fields that were successfully extracted.
images (object): An object with images. These include
- documentImage (string): Base64 string of the front photo of the document.
- documentBackImage (string): Base64 string of the back photo of the document (if supplied).
- portraitImage (string): Base64 string of the extracted face portrait image pulled from the document.

On Scan Error

This function is called when something goes wrong and an error occurs during data extraction. To hook onto the event, you may use the following code:

component.onScanError = function(error) {
    console.log('An error occurred: ', error);
}

The error parameter is of type string.

On Scan Cancelled

This function is called when a document scan for data extraction was started, but then cancelled before completion. To hook onto the event, you may use the following code:

component.onScanCancelled = function() {
    // Your code here
}

No parameter is passed to this function call.

On Before Scan

This function is called before the camera feed is launched when document scan starts. It is recommended to use this function to set the correlationId of the component by calling setCorrelationId(). To hook onto the event, you may use the following code:

component.onBeforeScan = function() {
    // Your code here
    // component.setCorrelationId('your-id-here');
}

No parameter is passed to this function call.

On Before Upload

This function is called before the file upload window appears. It is recommended to use this function to set the correlationId of the component by calling setCorrelationId(). To hook onto the event, you may use the following code:

component.onBeforeUpload = function() {
    // Your code here
    // component.setCorrelationId('your-id-here');
}

No parameter is passed to this function call.

Styling

The document scan component is structured a follows:

<div class="sybrin-identity-document-scan">
    <h2 class="sybrin-identity-document-scan-heading"></h2>
    <p class="sybrin-identity-document-scan-subtitle"></p>
    <div class="sybrin-identity-document-scan-image">
    </div>
    <div class="sybrin-identity-document-scan-instructions" style="display: none">
    </div>
    <div class="sybrin-identity-document-scan-video">
    </div>
    <p class="sybrin-identity-document-scan-button">
        <button class="sybrin-identity-document-scan-start"></button>
        <button class="sybrin-identity-document-scan-gotit" style="display: none"></button>
        <button class="sybrin-identity-document-scan-cancel" style="display: none"></button>
    </p>
    <p class="sybrin-identity-document-scan-upload">
        <a href="#" class="sybrin-identity-document-scan-upload-link"></a>
    </p>
    <p class="sybrin-identity-document-scan-company"></p>
</div>

The classes and elements specified above may be used to freely style the document scan component as desired. To do so, simply create a stylesheet and include it in the project, then style according to the above classes and elements.

Depending on component state, visibility of certain div elements alternates.

When idle...

sybrin-identity-document-scan-image is shown
sybrin-identity-document-scan-video is hidden
sybrin-identity-document-scan-start is shown
sybrin-identity-document-scan-cancel is hidden

When running identity data extraction...

sybrin-identity-document-scan-image is hidden
sybrin-identity-document-scan-video is shown
sybrin-identity-document-scan-start is hidden
sybrin-identity-document-scan-cancel is shown

Styling implementation example:

index.html

<html>
<head>
    <link rel="stylesheet" type="text/css" href="styles.css" media="screen"/>
</head>
<body>
    <div id='component'></div>
</body>
</html>

styles.css

.sybrin-identity-document-scan-button button {
    background: #963296;
}

Before styling

After styling

Last updated 2 years ago