Advanced Web Component Configuration

This page describes how to create, configure, and customize the Advanced Web Component, allowing you to manage the entire scope of document image recognition and other related operations. For more details about all available Web Components, see the overview.

Set Up Component

Step 1: Import Component

Import the class DocumentReaderProcessor into your .js file.

• With module bundler:

import { DocumentReaderProcessor } from '@regulaforensics/vp-frontend-document-components';

• Without module bundler:

import { DocumentReaderProcessor } from '/node_modules/@regulaforensics/vp-frontend-document-components/dist/main.js';

Step 2: Add Component

Add the video tag to the .html file, then prepare and initialize the DocumentReaderProcessor object:

const videoElement = document.getElementById('yourVideoElement');
const processor = new DocumentReaderProcessor(videoElement);

processor.recognizerProcessParam = {
  processParam: {
    scenario: 'MrzAndLocate',
  },
};
processor.imageProcessParam = {
  processParam: {
    scenario: 'MrzAndLocate',
  },
};

try {
   // Variant 1 - for production environment 
   await processor.initialize(); 

   // Variant 2 - for test-only environment 
   // await processor.initialize({ license: 'BASE64_LICENSE_KEY' });  

   const result = await processor.startRecognition();

   processor.stopRecognition();

   console.log(result);
} catch (e) {
   console.log(e);
}

In the preceding example, the DocumentReaderProcessor object is created using the HTML element with the ID yourVideoElement. After that, the processor component needs to be initialized with the license.

Step 3: Initialize Component

• Production environment. Domain name licensing is used, so don't add the license to the project source code:

await processor.initialize();

• Development environment. Use this option only when your product is under development or testing, and you still don't expose your application to the internet, as your license needs to be added to the project source code:

await processor.initialize({ license: 'BASE64_LICENSE_KEY' });

See how to convert a license file to the Base64 string.

Warning

Once the development is finished and your product is ready to be exposed to the internet, make sure that you have removed the license from your source code.

Step 4: Configure Resources Location (Optional)

Document Reader Web Components require several package files. By default, all the packages are downloaded from Regula servers, but you can also specify your own path to them. For details, see the Resources page.

After you have uploaded all the required package files, you can change the URL to your own:

const processor = new DocumentReaderProcessor(videoElement); 
processor.workerPath = 'https://custom-wasm-and-worker-files-path.com';

Available Methods

• initialize
• startRecognition
• processImage
• switchCamera
• stopRecognition

initialize

Initializes the DocumentReaderProcessor object. Accepts an object with a Base64-encoded license string.

Warning

Base64 license string is applied only to test environments, production mode must use the domain name licensing.

await processor.initialize({ license: 'BASE64_LICENSE_KEY' });

startRecognition

Launches the video stream and starts recognizing the document. Returns the result of document processing.

const result = await processor.startRecognition();

startRecognition may take the callback function with the object parameter currentPage holding the data of the page currently being processed.

The currentpage data fields include:

• currentPage.data — object with an intermediate processing result
• currentPage.startNextPage — method for starting the next page procession
• currentPage.finishRecognition — method for completing the entire process

The next example demonstrates the case, when recognition of the next page is delayed for 3 seconds (3000 ms). During this time, you may ask the user to turn the document over.

async function pageListener(currentPage) {
    setTimeout(async () => {               
        await currentPage.startNextPage(); 
    }, 3000);                              
}

const result = await processor.startRecognition(pageListener);

processImage

Processes the image files containing documents. Can take as a parameter a FileList or Blob array:

const file = '<FILELIST_or_BLOB_ARRAY>';

const result = await processor.processImage(file);

Note: For more information about the FileList and Blob types, see the links: FileList and Blob.

switchCamera

Switches the image recognition to the next camera (in case there are several available).

await processor.switchCamera();

stopRecognition

Stops the document recognition process and ends the video stream.

processor.stopRecognition();

Available Parameters

You can change the default configuration for video streaming and document recognition. The parameters must be set before the document recognition process starts.

• streamParam
• imageProcessParam
• recognizeListener
• videoElement
• isInitialized
• isProcessing

streamParam

The video streaming parameters.

processor.streamParam = {
   cameraMode: 'environment', 
   preferredCameraId: '',
   resolution: {
     width: 1280,
     height: 720, 
   },
}

See available streaming parameters in the following table.

Parameter	Default	Description	Values
cameraMode	'environment'	Camera facing mode.	'environment' 'user'
preferredCameraId	—	ID of the concrete camera to be used for the streaming. Can be extracted from navigator.mediaDevices.enumerateDevices().	strings with number and/or letters
resolution	'1280 x 720'	Resolution of the video stream.	string with numerics of width and height

recognizerProcessParam

The parameters for recognizing a document from the camera (by the startRecognition method).

See the following example with several parameters and their default values:

processor.recognizerProcessParam = {
   processParam: {
      returnUncroppedImage: true,
      returnPackageForReprocess: false,
   },
};

For more information, see the list of all available document processing params.

imageProcessParam

The settings for recognizing an image as a document file (by processImage method).

See the following example with several parameters and their default values:

// Default settings:
processor.imageProcessParam = {
   processParam: {
      returnUncroppedImage: true,
      returnPackageForReprocess: false,
   },
}

For more information, see the list of all available document processing params.

recognizeListener

The callback function that takes as a parameter the processing result for each frame (response).

See the following example, where the processing result for each frame is logged to the console:

function listener(response) {
  console.log(response);
}

processor.recognizeListener = listener;

Note: The listener for image recognizer is not set by default.

videoElement

The HTML element to display the video stream from the camera. This setting changes the video element that was defined during the processor object construction by the new DocumentReaderProcessor(videoElement).

See the example:

const videoElement = document.getElementById('HTMLVideoElement');

processor.videoElement = videoElement; // null by default

Note: By default, processor.videoElement is null.

isInitialized

Read-only property. true if the processor has been initialized.

processor.isInitialized;

isProcessing

Read-only property. true if document recognition is still in progress.

processor.isProcessing;

Next Steps

• Resources
• Examples
• FAQ