Skip to content

Events and Actions for Web Components

Overview

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

For example, the next code snippet adds event listeners to document-reader and camera-snapshot components:

const documentReaderComponent = document.querySelector('document-reader'); 
const cameraSnapshotComponent = document.querySelector('camera-snapshot');

documentReaderComponent.addEventListener('document-reader', (event) => console.log(event.detail));
cameraSnapshotComponent.addEventListener('camera-snapshot', (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: 'PRESS_CAMERA_BUTTON',
  data: null,
}

The fields of the event.detail object:

  • action — contains the type of action that generated the component's event. For details, see action types.
  • data — keeps the object with status of executed action and the payload. For details, see action data.

Action Types

Action type Description Related components and events
ELEMENT_VISIBLE Component is appended in the DOM. document-reader, camera-snapshot
PRESS_CAMERA_BUTTON Camera button is pressed. document-reader, camera-snapshot
PRESS_FILE_BUTTON Files button is pressed. document-reader, camera-snapshot
PRESS_RETRY_BUTTON Retry button is pressed. document-reader, camera-snapshot
PRESS_SKIP_BUTTON Skip button is pressed. document-reader
PRESS_CAPTURE_BUTTON Capture button is pressed. document-reader, camera-snapshot
PRESS_CHANGE_CAMERA_BUTTON Change camera button is pressed. document-reader, camera-snapshot
PRESS_REMOTE_DEVICE_BUTTON Mobile device button is pressed. document-reader
PRESS_MIRRORING_BUTTON Mirroring button is pressed. document-reader, camera-snapshot
NEW_PAGE_AVAILABLE document contains another page. document-reader
NEW_PAGE_STARTED Recognition of a new page has started. document-reader
CLOSE Close button is pressed. document-reader, camera-snapshot
CAMERA_PROCESS_CLOSED Close button is pressed on the document recognition screen. document-reader, camera-snapshot
CAMERA_PROCESS_STARTED Recognition from the camera has started. document-reader
VIDEO_STARTED Video stream started. document-reader, camera-snapshot
VIDEO_STOPPED Video stream stopped. document-reader, camera-snapshot
FILE_PROCESS_STARTED File processing has started. document-reader, camera-snapshot
PROCESS_FINISHED The component has finished its work. document-reader, camera-snapshot
SERVICE_INITIALIZED The component has started its work. document-reader
REMOTE_TRANSACTION_UPLOADED Remote transaction with current tag was uploaded.
For more details, see remote action data.		 document-reader
REMOTE_PROCESS_FINISHED Remote transaction with current tag was processed. document-reader

Action Data

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

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

If the video recording is enabled:

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

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.
  • video — video of the document scanning process (if the videoRecord setting is set).

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

{
  reason: '<FAILURE_REASON>',
  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 Failure Reasons

Reason Description
WASM_ERROR Error in WASM
WASM_LICENSE Missing or incorrect license
FILE_SIZE File size is too large
INCORRECT_FILE Problems with reading the file
INCORRECT_SCENARIO Scenario is not supported
MISSING_SCENARIO Scenario is missing
UNKNOWN_ERROR Unknown error
NOT_SUPPORTED Browser is not supported
HTTP_NOT_SUPPORTED Web component doesn't operate over the HTTP protocol
INSECURE_PAGE_CONTEXT Web component doesn't work in insecure context
CAMERA_UNKNOWN_ERROR Unknown camera error
CAMERA_PERMISSION_DENIED Access to the camera is denied
NO_CAMERA No camera available
INCORRECT_CAMERA_ID Camera with requested ID was not found
CONNECTION_ERROR Connection errors
BAD_CONFIGURATION Incompatible component settings are applied

Action Statuses

Status Description
0 Failure
1 Success
2 Timeout

Remote Action Data

In case of REMOTE_TRANSACTION_UPLOADED action, the object event.detail will contain the following data:

{
  action: EventActions.REMOTE_TRANSACTION_UPLOADED, 
  data: {
    id: <TRANSACTION_ID>, 
    state: 1, 
    updatedAt: 'dateStr'
  },
}

Transaction ID can be used to trigger the server-side reprocessing.

Logic of Event Generation

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

Event condition Event type Event object event.detail Description
Component is mounted in the DOM. document-reader, camera-snapshot 
{
  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></document-reader>
</div>
Camera button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_CAMERA_BUTTON', 
  data: null,
}
Files button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_FILE_BUTTON', 
  data: null,
}
Retry button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_RETRY_BUTTON', 
  data: null,
}
Skip page button is pressed. document-reader 
{
  action: 'PRESS_SKIP_BUTTON', 
  data: null,
}
Available only in document-reader.
Capture button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_CAPTURE_BUTTON', 
  data: null,
}
Change camera button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_CHANGE_CAMERA_BUTTON', 
  data: null,
}
Mobile device button is pressed. document-reader 
{
  action: 'PRESS_REMOTE_DEVICE_BUTTON', 
  data: null,
}
Mirroring button is pressed. document-reader, camera-snapshot 
{
  action: 'PRESS_MIRRORING_BUTTON', 
  data: null,
}
The document contains another page. document-reader 
{
  action: 'NEW_PAGE_AVAILABLE', 
  data: null,
}
Available only in document-reader.
Recognition of a new page has started. document-reader 
{
  action: 'NEW_PAGE_STARTED', 
  data: null,
}
Available only in document-reader.
Close button is pressed. document-reader, camera-snapshot 
{
  action: 'CLOSE', 
  data: null,
}
Close button is pressed on the document recognition screen. document-reader, camera-snapshot 
{
  action: 'CAMERA_PROCESS_CLOSED', 
  data: null,
}
Recognition from the camera has started. document-reader, camera-snapshot 
{
  action: 'CAMERA_PROCESS_STARTED', 
  data: null,
}
Video stream has started. document-reader, camera-snapshot 
{
  action: 'VIDEO_STARTED', 
  data: null,
}
Video stream has stopped. document-reader, camera-snapshot 
{
  action: 'VIDEO_STOPPED', 
  data: null,
}
File processing has started. document-reader, camera-snapshot 
{
  action: 'FILE_PROCESS_STARTED', 
  data: null,
}
Operation of the component is completed successfully. document-reader, camera-snapshot 
{
  action: 'PROCESS_FINISHED', 
  data: {
    response: { ... },
    status: 1
  }
}
Operation of the component is completed by timeout. document-reader 
{
  action: 'PROCESS_FINISHED', 
  data: {
    response: { ... },
    status: 2
  }
}
Available only in document-reader.
Operation of the component failed. document-reader, camera-snapshot 
{
  action: 'PROCESS_FINISHED', 
  data: {
    reason: 'CAMERA_PERMISSION_DENIED',
    status: 0
  }
}
Component is initialized and ready to work. document-reader 
{
  action: 'SERVICE_INITIALIZED',
  data: null,
}
Available only in document-reader.
Transaction has been successfully uploaded from the delegated device. document-reader 
{
  action: 'REMOTE_TRANSACTION_UPLOADED',
  data: {
    id: 'df4e210a-8411-411b-998e-a7c7f6b4a770',
    state: 1,
    updatedAt: '2024-09-19T11:05:21.473286Z'       
  },
}
Available only in document-reader.
Remote processing has been completed successfully. document-reader 
{
  action: 'REMOTE_PROCESS_FINISHED',
  data: {
    response: { ... },
    status: 1       
  },
}
Available only in document-reader.

Next Steps