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 thevideoRecord
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
|
|
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:
|
Camera button is pressed. |
document-reader , camera-snapshot
|
|
|
Files button is pressed. |
document-reader , camera-snapshot
|
|
|
Retry button is pressed. |
document-reader , camera-snapshot
|
|
|
Skip page button is pressed. |
document-reader
|
|
Available only in document-reader .
|
Capture button is pressed. |
document-reader , camera-snapshot
|
|
|
Change camera button is pressed. |
document-reader , camera-snapshot
|
|
|
Mobile device button is pressed. |
document-reader
|
|
|
Mirroring button is pressed. |
document-reader , camera-snapshot
|
|
|
The document contains another page. |
document-reader
|
|
Available only in document-reader .
|
Recognition of a new page has started. |
document-reader
|
|
Available only in document-reader .
|
Close button is pressed. |
document-reader , camera-snapshot
|
|
|
Close button is pressed on the document recognition screen. |
document-reader , camera-snapshot
|
|
|
Recognition from the camera has started. |
document-reader , camera-snapshot
|
|
|
Video stream has started. |
document-reader , camera-snapshot
|
|
|
Video stream has stopped. |
document-reader , camera-snapshot
|
|
|
File processing has started. |
document-reader , camera-snapshot
|
|
|
Operation of the component is completed successfully. |
document-reader , camera-snapshot
|
|
|
Operation of the component is completed by timeout. |
document-reader
|
|
Available only in document-reader .
|
Operation of the component failed. |
document-reader , camera-snapshot
|
|
|
Component is initialized and ready to work. |
document-reader
|
|
Available only in document-reader .
|
Transaction has been successfully uploaded from the delegated device. |
document-reader
|
|
Available only in document-reader .
|
Remote processing has been completed successfully. |
document-reader
|
|
Available only in document-reader .
|
Event Response
You can get the response of the component's event in the detail.data.response
field of the event object. For example:
const component = document.querySelector('document-reader');
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', listener);
To get the processing results for each frame, you can set the callback function as in the following example:
window.RegulaDocumentSDK.recognizeListener = (response) => console.log(response);