Document Reader Device

• Overview
• Predefined UI Component
  • npm Service Integration
  • Events
    • Action Types
    • Action Data
    • Action Statuses
    • Action Failure Reasons
    • Event Generation Logic
    • Event Response
  • Settings and Attributes
  • Appearance Customization
    • Font and Colors
• Document Reader Controller
  • npm Controller Integration
  • Controller Methods
  • Controller Parameters
• Examples

Overview

The Document Reader Device package contains:

• Predefined UI Component
  Document Reader UI Web Component with predefined view and behavior are designed for documents recognition with Document Reader Web Service. You can still customize most of the appearance and processing parameters before the launch if needed.
• Controller
  Document Reader Controller serves as the proxy, delegating the entire processing to external service.

Predefined UI Component

npm Service Integration

Step 1. Install the package @regulaforensics/vp-frontend-document-device:

npm i @regulaforensics/vp-frontend-document-device

Step 2. Import the function defineComponents into your .js file.

Using module bundler:

import { defineComponents } from '@regulaforensics/vp-frontend-document-device';

Without module bundler:

import { defineComponents } from './node_modules/@regulaforensics/vp-frontend-document-device/index.js';

Step 3. Define the components, depending on the functionality that you need.

Call the defineComponents() method without arguments:

defineComponents();

Step 4. Add the component tag to the .html file.

<document-reader-device></document-reader-device>

Events

The main idea of a subscription to different events is to detect the specific state changes of the component. For the convenience, the event has the same name as the component that it belongs to.

For example, the next code snippet adds the event listeners to document-reader-device component:

const documentReaderComponent = document.querySelector('document-reader-device'); 

documentReaderComponent.addEventListener('document-reader-device', (event) => console.log(event.detail));

To provide the detailed information about how the event was generated and executed, the special object event.detail is generated. See event.detail object structure in the following code snippet:

{
  action: 'ELEMENT_VISIBLE',
  data: null,
}

The fields of the event.detail object:

• action contains the type of action that generated the component event. For more information, see all available action types.
• data keeps the object with status of executed action and the payload. For more information, see the action data section.

Action Types

| Type of action | Description of the action | |:-----------------------------|:------------------------------------------------------------------| | ELEMENT_VISIBLE | Component is appended in the DOM. | | PRESS_RETRY_BUTTON | The "Retry" button is pressed. | | PRESS_CONNECT_BUTTON | The "Connect" button is pressed. | | PRESS_DISCONNECT_BUTTON | The "Disconnect" button is pressed. | | PRESS_AUTOSCAN_BUTTON | The "Auto scan" button is pressed. | | PRESS_PROCESS_BUTTON | The "Process" button is pressed. | | CLOSE | The "Close" button is pressed. | | PROCESS_STARTED | Document processing has started. | | PROCESS_FINISHED | The component has finished its work. |

Action Data

1. In case of successful operation, the event.detail.data field is structured as follows:

{
  response: { ... },
  status: 1
}

Available fields of event.detail.data object:

• response contains the object with resulting payload of the event's action execution.
• status defines the status of event's action completion. For details, see action statuses.

2. In case of event's action failure, the event.detail.data field is structured as follows:

{
  reason: 'CONNECTION_ERROR',
  status: 0
}

Available fields of event.detail.data object:

• reason defines the reason of action's failure. For details, see failure reasons.
• status defines the status of event's action completion. For details, see action statuses.

Action Statuses

| Status | Description | |:-------|:------------| | 0 | Failure | | 1 | Success |

Action Failure Reasons

| Reason | Description of the reason | |:---------------------------|:-----------------------------------| | UNKNOWN_ERROR | Unknown error | | NOT_SUPPORTED | The browser is not supported | | CONNECTION_ERROR | Connection errors |

Event Generation Logic

The cases of event generation are described in the following table.

Event object event.detail

document-reader, camera-snapshot, document-reader-device

{
  action: 'ELEMENT_VISIBLE', 
  data: null,
}

To receive this event, you must wrap the component in another element (for example, a div) and add an addEventListener to it. When the component appears in the DOM, the event will pop up.

For example:

<div id="add-event-listener-to-this-element">
  <document-reader-device></document-reader-device>
</div>

{
  action: 'PRESS_RETRY_BUTTON', 
  data: null,
}

{
  action: 'PRESS_CONNECT_BUTTON', 
  data: null,
}

{
  action: 'PRESS_DISCONNECT_BUTTON', 
  data: null,
}

{
  action: 'PRESS_AUTOSCAN_BUTTON', 
  data: null,
}

{
  action: 'PRESS_PROCESS_BUTTON', 
  data: null,
}

{
  action: 'CLOSE', 
  data: null,
}

{
  action: 'PROCESS_STARTED', 
  data: null,
}

{
  action: 'PROCESS_FINISHED', 
  data: {
    response: { ... },
    status: 1
  }
}

{
  action: 'PROCESS_FINISHED', 
  data: {
    reason: 'UNKNOWN_ERROR',
    status: 0
  }
}

Event Response

You can get the response of the component event in the detail.data.response field of the event object. For example:

const component = document.querySelector('document-reader-device');

function listener(event) {
    if (event.detail.action === 'PROCESS_FINISHED' && event.detail.data.status === 1) {
        const response = event.detail.data.response;
        console.log(response);
    }
}

component.addEventListener('document-reader-device', listener);

Settings and Attributes

Define the element settings using the settings property of the JavaScript object. See the description and examples below.

  const element = document.createElement('document-reader-device');
  
  element.settings = {
    copyright: false,
    closeButton: false,
  };

See all component's settings and attributes in the following table.

| Setting name | Description | Data type | Default value | Values | |:----------------|:------------------------------------------------------------|:---------:|:-------------:|:---------------------------:| | nonce | Sets the unique nonce value to maintain the CSP policy. | string | undefined | unique nonce value | | serviceUrl | Sets the address of the Regula Document Reader Web Service. | string | | any URL | | properties | Sets an object with processing parameters. | object | undefined | { propertyName: 'value' } | | closeButton | Show the close button. | boolean | true | true, false | | copyright | Show Regula copyright footer. | boolean | true | true, false |

Appearance Customization

Font and Colors

Using CSS variables, you can change the font and the main colors of the components. See the table for the details.

| Variable | Info | Default value | |:-------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------------:| | --font-family | The font family of all text elements. If you change the font family, make sure to adjust the font size so the message on the start screen would fit the frame. | Noto Sans, sans-serif | | --font-size | The font size for the text elements. | 16px | | --main-color | Color for the graphic elements of the component. By default, the brand Regula violet is set. | #bd7dff | | --hover-color | Buttons hover color. | #c994ff | | --active-color | Buttons active color. | #bd7dff |

The following example demonstrates the document-reader-device HTML element font and color customization via the custom CSS class:

CSS:

.my-custom-style {
    --font-family: Arial, sans-serif;
    --main-color: green;
}

HTML:

<document-reader-device class="my-custom-style"></document-reader-device>

Document Reader Controller

DocumentReaderController serves as a proxy, delegating the entire processing to external Document Reader Web Service. The document-reader-device component is created on its basis.

npm Controller Integration

Step 1. Install the package @regulaforensics/vp-frontend-document-device

npm i @regulaforensics/vp-frontend-document-device

Step 2. Import the class DocumentReaderController into your .js file.

Using module bundler:

import { DocumentReaderController } from '@regulaforensics/vp-frontend-document-device';

Without module bundler:

import { DocumentReaderController } from '/node_modules/@regulaforensics/vp-frontend-document-device/index.js';

Step 3. Set the Document Reader Web Service URL and initialize the service:

const service = new DocumentReaderController('SERVICE_URL');

await service.initRegulaReader();

In the previous code fragment you need to replace SERVICE_URL placeholder with your actual service URL.

To get the processing results, you need to subscribe to the OnProcessingFinished event and use getLastResults method:

const responseListener = async () => {
  const response = await service.getLastResults();
  console.log(response);
};

service.hubProxy?.on('OnProcessingFinished', responseListener);

Controller Methods

initRegulaReader

Initializes the controller.

await service.initRegulaReader();

getLastResults

Returns the last processing result.

const response = await service.getLastResults();

getImages

Starts processing document manually.

await service.getImages();

setPropertyValue

Sets one specific device's property.

await service.setPropertyValue('AutoScan', false);

getPropertyValue

Gets one specific device's property.

const property = await service.getPropertyValue('AutoScan');

getAvailableDevices(index)

Returns device name specified by index argument from the list of available devices.

const device = await service.getAvailableDevices(0);

clearResults

Clears all previous scanning results.

await service.clearResults();

healthCheck

Returns the device status.

const status = await service.healthCheck();

stop

Disconnects from the service.

service.stop();

Controller Parameters

isInitialized

Read-only property. true` if the controller has been initialized.

service.isInitialized;

hubProxy

The object for setting/unsetting Sets event listeners.

Example of subscribing to events:

const onStartListener = () => console.log('Process started');
const onFinishListener = () => console.log('Process finished');

service.hubProxy?.on('OnProcessingStarted', onStartListener);
service.hubProxy?.on('OnProcessingFinished', onFinishListener);

Example of unsubscribing from events:

const onStartListener = () => console.log('Process started');
const onFinishListener = () => console.log('Process finished');

service.hubProxy?.off('OnProcessingStarted', onStartListener);
service.hubProxy?.off('OnProcessingFinished', onFinishListener);

Examples

You can see the examples of using the components on the Samples page.