@regulaforensics/vp-frontend-document-components 7.2.1756-nightly → 7.2.1829-nightly

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,14 +11,17 @@
11
11
  * [Events](#events)
12
12
  * [Action Types](#action-types)
13
13
  * [Action Data](#action-data)
14
+ * [Remote action data](#remote-action-data)
14
15
  * [Action Statuses](#action-statuses)
15
16
  * [Action Failure Reasons](#action-failure-reasons)
16
17
  * [Event Generation Logic](#event-generation-logic)
17
18
  * [Event Response](#event-response)
18
19
  * [Settings and Attributes](#settings-and-attributes)
19
20
  * [Backend reprocessing](#backend-reprocessing)
21
+ * [Delegating scan to device with better camera](#delegating-scan-to-device-with-better-camera)
20
22
  * [Appearance Customization](#appearance-customization)
21
23
  * [Font and Colors](#font-and-colors)
24
+ * [Inserting component in Flex and Grid layouts](#inserting-component-in-flex-and-grid-layouts)
22
25
  * [Localized Messages](#localized-messages)
23
26
  * [Document Reader Processor](#document-reader-processor)
24
27
  * [npm Processor Integration](#npm-processor-integration)
@@ -41,8 +44,8 @@ The Document Reader Web Components let you add document verification to your web
41
44
  * Capture a document from the device's camera
42
45
  * Process an uploaded image
43
46
  * Crop the image by document boundaries
44
- * Detect the presence of a machine-readable zone (MRZ)
45
- * Recognize and return the values of MRZ text fields
47
+ * Detect the presence of a machine-readable zone (MRZ), recognize it, and parse into text text fields
48
+ * Read barcodes, and parse them into text fields
46
49
 
47
50
  The Document Reader Web Components package contains:
48
51
 
@@ -232,7 +235,14 @@ After adding `DocumentReaderService` to the global variable, you can change the
232
235
  },
233
236
  };
234
237
  ```
235
-
238
+
239
+ **Session ID** for video processing:
240
+ ```javascript
241
+ window.RegulaDocumentSDK.recognizerProcessParam = {
242
+ tag: 'your session id',
243
+ };
244
+ ```
245
+
236
246
  **Image processing** default settings. The functionality is available via the gallery button.
237
247
  ```javascript
238
248
  window.RegulaDocumentSDK.imageProcessParam = {
@@ -289,6 +299,7 @@ After adding `DocumentReaderService` to the global variable, you can change the
289
299
  | **parseBarcodes** | This option can be disabled to stop parsing after barcode is read. | boolean | `true` | `true`, `false` |
290
300
  | **splitNames** | When enabled, the Surname and GivenNames fields will be divided into ft_First_Name, ft_Second_Name, ft_Third_Name, ft_Fourth_Name, ft_Last_Name fields. | boolean | `false` | `true`, `false` |
291
301
  | **backendProcessing** | When enabled, it prepares the processing result to be sent to the backend for re-processing. Use ```service.finalizePackage();``` after receiving the processing results to send them to the backend. | Object | {} | { serviceURL: 'URL', httpHeaders: { key1: 'header1', key2: 'header2', ... } } |
302
+ | **generateNumericCodes** | This parameter is used to generate numeric representation for issuing state and nationality codes. | boolean | | `true`, `false` |
292
303
 
293
304
  **Attention!** If the `multipage-processing` or `internal-scenario` attributes are set, the corresponding `multipageProcessing` and `scenario` parameters' values are ignored.
294
305
 
@@ -323,26 +334,29 @@ The fields of the `event.detail` object:
323
334
 
324
335
  #### Action Types
325
336
 
326
- | Type of action | Description of the action | Components and events, where present |
327
- |:-----------------------------|:------------------------------------------------------------------|:------------------------------------:|
328
- | `ELEMENT_VISIBLE` | Component is appended in the DOM. | `document-reader`, `camera-snapshot` |
329
- | `PRESS_CAMERA_BUTTON` | The "From camera" button is pressed. | `document-reader`, `camera-snapshot` |
330
- | `PRESS_FILE_BUTTON` | The "From gallery" button is pressed. | `document-reader`, `camera-snapshot` |
331
- | `PRESS_RETRY_BUTTON` | The "Retry" button is pressed. | `document-reader`, `camera-snapshot` |
332
- | `PRESS_SKIP_BUTTON` | The "Skip" button is pressed. | `document-reader` |
333
- | `PRESS_CAPTURE_BUTTON` | The "Capture" button is pressed. | `document-reader`, `camera-snapshot` |
334
- | `PRESS_CHANGE_CAMERA_BUTTON` | The "Change camera" button is pressed. | `document-reader`, `camera-snapshot` |
335
- | `PRESS_MIRRORING_BUTTON` | The "Mirroring" button is pressed. | `document-reader`, `camera-snapshot` |
336
- | `NEW_PAGE_AVAILABLE` | The document contains another page. | `document-reader` |
337
- | `NEW_PAGE_STARTED` | Recognition of a new page has started. | `document-reader` |
338
- | `CLOSE` | The "Close" button is pressed. | `document-reader`, `camera-snapshot` |
339
- | `CAMERA_PROCESS_CLOSED` | The "Close" button is pressed on the document recognition screen. | `document-reader`, `camera-snapshot` |
340
- | `CAMERA_PROCESS_STARTED` | Recognition from the camera has started. | `document-reader` |
341
- | `VIDEO_STARTED` | Video stream started. | `document-reader`, `camera-snapshot` |
342
- | `VIDEO_STOPPED` | Video stream stopped. | `document-reader`, `camera-snapshot` |
343
- | `FILE_PROCESS_STARTED` | File processing has started. | `document-reader`, `camera-snapshot` |
344
- | `PROCESS_FINISHED` | The component has finished its work. | `document-reader`, `camera-snapshot` |
345
- | `SERVICE_INITIALIZED` | The component has started its work. | `document-reader` |
337
+ | Type of action | Description of the action | Components and events, where present |
338
+ |:------------------------------|:------------------------------------------------------------------|:------------------------------------:|
339
+ | `ELEMENT_VISIBLE` | Component is appended in the DOM. | `document-reader`, `camera-snapshot` |
340
+ | `PRESS_CAMERA_BUTTON` | The "From camera" button is pressed. | `document-reader`, `camera-snapshot` |
341
+ | `PRESS_FILE_BUTTON` | The "From gallery" button is pressed. | `document-reader`, `camera-snapshot` |
342
+ | `PRESS_RETRY_BUTTON` | The "Retry" button is pressed. | `document-reader`, `camera-snapshot` |
343
+ | `PRESS_SKIP_BUTTON` | The "Skip" button is pressed. | `document-reader` |
344
+ | `PRESS_CAPTURE_BUTTON` | The "Capture" button is pressed. | `document-reader`, `camera-snapshot` |
345
+ | `PRESS_CHANGE_CAMERA_BUTTON` | The "Change camera" button is pressed. | `document-reader`, `camera-snapshot` |
346
+ | `PRESS_MIRRORING_BUTTON` | The "Mirroring" button is pressed. | `document-reader`, `camera-snapshot` |
347
+ | `NEW_PAGE_AVAILABLE` | The document contains another page. | `document-reader` |
348
+ | `NEW_PAGE_STARTED` | Recognition of a new page has started. | `document-reader` |
349
+ | `CLOSE` | The "Close" button is pressed. | `document-reader`, `camera-snapshot` |
350
+ | `CAMERA_PROCESS_CLOSED` | The "Close" button is pressed on the document recognition screen. | `document-reader`, `camera-snapshot` |
351
+ | `CAMERA_PROCESS_STARTED` | Recognition from the camera has started. | `document-reader` |
352
+ | `VIDEO_STARTED` | Video stream started. | `document-reader`, `camera-snapshot` |
353
+ | `VIDEO_STOPPED` | Video stream stopped. | `document-reader`, `camera-snapshot` |
354
+ | `FILE_PROCESS_STARTED` | File processing has started. | `document-reader`, `camera-snapshot` |
355
+ | `PROCESS_FINISHED` | The component has finished its work. | `document-reader`, `camera-snapshot` |
356
+ | `SERVICE_INITIALIZED` | The component has started its work. | `document-reader` |
357
+ | `PRESS_REMOTE_DEVICE_BUTTON` | The "From other phone" button is pressed. | `document-reader` |
358
+ | `REMOTE_TRANSACTION_UPLOADED` | Remote transaction with current tag was uploaded | `document-reader` |
359
+ | `REMOTE_PROCESS_FINISHED` | Remote transaction with current tag was processed | `document-reader` |
346
360
 
347
361
 
348
362
  #### Action Data
@@ -394,21 +408,38 @@ Available fields of `event.detail.data` object:
394
408
 
395
409
  #### Action Failure Reasons
396
410
 
397
- | Reason | Description of the reason |
398
- |:---------------------------|:-----------------------------------|
399
- | `WASM_ERROR` | Error in WASM |
400
- | `WASM_LICENSE` | Missing or incorrect license |
401
- | `FILE_SIZE` | The file size is too large |
402
- | `INCORRECT_FILE` | Problems with reading the file |
403
- | `INCORRECT_SCENARIO` | Scenario is not supported |
404
- | `MISSING_SCENARIO` | Scenario is missing |
405
- | `UNKNOWN_ERROR` | Unknown error |
406
- | `NOT_SUPPORTED` | The browser is not supported |
407
- | `CAMERA_UNKNOWN_ERROR` | Unknown camera error |
408
- | `CAMERA_PERMISSION_DENIED` | Access to the camera is prohibited |
409
- | `NO_CAMERA` | There is no camera available |
410
- | `INCORRECT_CAMERA_ID` | Camera with this ID was not found |
411
- | `CONNECTION_ERROR` | Connection errors |
411
+ | Reason | Description of the reason |
412
+ |:---------------------------|:-------------------------------------------------------|
413
+ | `WASM_ERROR` | Error in WASM |
414
+ | `WASM_LICENSE` | Missing or incorrect license |
415
+ | `FILE_SIZE` | The file size is too large |
416
+ | `INCORRECT_FILE` | Problems with reading the file |
417
+ | `INCORRECT_SCENARIO` | Scenario is not supported |
418
+ | `MISSING_SCENARIO` | Scenario is missing |
419
+ | `UNKNOWN_ERROR` | Unknown error |
420
+ | `NOT_SUPPORTED` | The browser is not supported |
421
+ | `HTTP_NOT_SUPPORTED` | The web component does not work over the http protocol |
422
+ | `INSECURE_PAGE_CONTEXT` | The web component does not work in insecure context |
423
+ | `CAMERA_UNKNOWN_ERROR` | Unknown camera error |
424
+ | `CAMERA_PERMISSION_DENIED` | Access to the camera is prohibited |
425
+ | `NO_CAMERA` | There is no camera available |
426
+ | `INCORRECT_CAMERA_ID` | Camera with this ID was not found |
427
+ | `CONNECTION_ERROR` | Connection errors |
428
+
429
+ #### Remote action data
430
+
431
+ **1.** In case of remote scan scenario REMOTE_TRANSACTION_UPLOADED `event.detail` will contain the following data:
432
+ ```javascript
433
+ {
434
+ action: EventActions.REMOTE_TRANSACTION_UPLOADED,
435
+ data: {
436
+ id: 1,
437
+ state: 1,
438
+ updatedAt: 'dateStr'
439
+ },
440
+ }
441
+ ```
442
+ Transaction id can be used to trigger reprocessing.
412
443
 
413
444
  #### Event Generation Logic
414
445
 
@@ -975,6 +1006,41 @@ function listener(event) {
975
1006
 
976
1007
  component.addEventListener('document-reader', listener);
977
1008
  ```
1009
+ ### Delegating scan to device with better camera
1010
+
1011
+ For cases when user's main device lacks camera or does not succeed to scan with given camera quality,
1012
+ you have an option to delegate scanning to another available device (i.e. phone).
1013
+
1014
+ #### 1. "From other phone" action may be configured on the start screen:
1015
+ - configure [backend reprocessing](#backend-reprocessing)
1016
+ - add 'delegateURL' and 'tag':
1017
+ ```javascript
1018
+ processor.recognizerProcessParam = {
1019
+ delegateURL: 'https://your-page.com?tag={tag}', // the page which will be used by other device
1020
+ tag: 123 // your session id, will be added to delegateURL in place of {tag} substring
1021
+ }
1022
+ ```
1023
+ - these settings will unlock "From other phone" option
1024
+ that shows the user QR Code with url (i.e. `https://your-page.com?tag=123`)
1025
+ - the component will emit **REMOTE_TRANSACTION_UPLOADED** event with the most recent transaction uploaded with your session tag.
1026
+ Transaction id may be used to trigger full process backend reprocessing (i.e use [Document Reader Webclient](https://www.npmjs.com/package/@regulaforensics/document-reader-webclient))
1027
+ - the component will emit **REMOTE_PROCESS_FINISHED** event with a result of the most recent processed transaction.
1028
+ It is similar to **PROCESS_FINISHED** event but may contain more data due to backend reprocessing
1029
+
1030
+ #### 2. Configure Delegate page component on delegateURL:
1031
+ - configure [backend reprocessing](#backend-reprocessing)
1032
+ - use the same tag as on the main page
1033
+ ```javascript
1034
+ window.RegulaDocumentSDK.recognizerProcessParam = {
1035
+ tag: 123 // your session id, i.e. it can be extracted from your delegate page URL
1036
+ };
1037
+
1038
+ element.settings = {
1039
+ startScreen: false, // From camera recognition is expected
1040
+ }
1041
+ ```
1042
+ - use finalizePackage() to send the data for further reprocessing
1043
+
978
1044
 
979
1045
  ### Appearance Customization
980
1046
 
@@ -1006,6 +1072,19 @@ HTML:
1006
1072
  ```html
1007
1073
  <document-reader class="my-custom-style"></document-reader>
1008
1074
  ```
1075
+ #### Inserting component in Flex and Grid layouts
1076
+
1077
+ document-reader and camera-snapshot components have **width** and **height** set to **100%** by default and therefore try to fit their container element.
1078
+ This should not affect correct CSS Grid positioning, but for Flexbox make sure to style document-reader dimensions and set **flex-basis**, i.e.:
1079
+
1080
+ ```css
1081
+ document-reader.flex-item {
1082
+ width: auto;
1083
+ height: auto;
1084
+ flex-basis: 500px; // distinct width of your choice
1085
+ }
1086
+ ```
1087
+
1009
1088
 
1010
1089
  #### Localized Messages
1011
1090
 
@@ -1042,6 +1121,7 @@ See the following table with localized labels, used in the components.
1042
1121
  | **tryAgain** | Try again | `document-reader`, `camera-snapshot` |
1043
1122
  | **fromCamera** | From camera | `document-reader`, `camera-snapshot` |
1044
1123
  | **fromGallery** | From gallery | `document-reader`, `camera-snapshot` |
1124
+ | **fromOtherPhone** | From other phone | `document-reader`, `camera-snapshot` |
1045
1125
  | **cameraUnavailable** | Camera unavailable! | `document-reader`, `camera-snapshot` |
1046
1126
  | **preparingCamera** | Preparing the camera... | `document-reader`, `camera-snapshot` |
1047
1127
  | **noCameraAvailable** | No camera available | `document-reader`, `camera-snapshot` |
@@ -1055,6 +1135,8 @@ See the following table with localized labels, used in the components.
1055
1135
  | **largeFile** | This file is too large to be uploaded | `document-reader` |
1056
1136
  | **selectSmallerFile** | Please select a smaller file | `document-reader` |
1057
1137
  | **versionNotSupported** | Your browser version is not supported | `document-reader` |
1138
+ | **httpNotSupported** | HTTPS is not used. | `document-reader` |
1139
+ | **insecurePageContext** | Insecure page context. | `document-reader` |
1058
1140
  | **updateBrowser** | Update your browser version | `document-reader` |
1059
1141
  | **licenseError** | A license error has occurred | `document-reader` |
1060
1142
  | **licenseExpired** | The license cannot be found or has expired | `document-reader` |
@@ -1070,6 +1152,9 @@ See the following table with localized labels, used in the components.
1070
1152
  | **flipDocument** | Flip the document | `document-reader` |
1071
1153
  | **verified** | Verified! | `document-reader` |
1072
1154
  | **keepDeviceStill** | Hold the device still | `document-reader` |
1155
+ | **otherDeviceCardTitle** | Continue on your phone | `document-reader` |
1156
+ | **otherDeviceCardSubtitle** | The camera quality on the phone is better | `document-reader` |
1157
+ | **otherDeviceCardNote** | Scan QR on your phone | `document-reader` |
1073
1158
  | **positionDocumentCenter** | Position the document in the center | `camera-snapshot` |
1074
1159
  | **photoCapturedSuccessfully** | The photo is captured successfully. | `camera-snapshot` |
1075
1160
  | **uploadPhoto** | Upload a photo | `camera-snapshot` |
@@ -1408,8 +1493,7 @@ By default, these files are downloaded from Regula servers, but you can set your
1408
1493
 
1409
1494
  **1.** To download these files from our server to local machine, you can get the link in the `window.RegulaDocumentSDK.workerPath` field.
1410
1495
 
1411
- **2.** Then, in the `ProcMgr.worker.js` file, use the search to find `https://wasm.regulaforensics.com` and replace the full link with your custom URL.
1412
- Upload all three files (`ProcMgr.worker.js`, `ProcMgr.wasm`, `ProcMgr.data`) to the location you specified. Also, change the address in `windows.RegulaDocumentSDK`.
1496
+ **2.** Upload all three files (`ProcMgr.worker.js`, `ProcMgr.wasm`, `ProcMgr.data`) to the location you specified. Also, change the address in `windows.RegulaDocumentSDK`.
1413
1497
 
1414
1498
  For Predefined UI Components:
1415
1499
 
package/dist/index.d.ts CHANGED
@@ -27,7 +27,7 @@ declare enum CameraSnapshotAttributes {
27
27
  closeButton = "close-button"
28
28
  }
29
29
 
30
- export declare type CameraSnapshotDetailType = DetailEvent<EventActions, CameraSnapshotResponseType>;
30
+ export declare type CameraSnapshotDetailType = DetailEvent<Exclude<EventActions, EventActions.REMOTE_TRANSACTION_UPLOADED>, CameraSnapshotResponseType>;
31
31
 
32
32
  export declare type CameraSnapshotResponseType = Array<{
33
33
  raw: string;
@@ -118,7 +118,7 @@ export declare class DocumentReaderCaptureWebComponent extends HTMLElement {
118
118
  disconnectedCallback(): void;
119
119
  }
120
120
 
121
- export declare type DocumentReaderDetailType = DetailEvent<EventActions, DocumentReaderResponseType>;
121
+ export declare type DocumentReaderDetailType = DetailEvent<Exclude<EventActions, EventActions.REMOTE_TRANSACTION_UPLOADED>, DocumentReaderResponseType>;
122
122
 
123
123
  export declare interface DocumentReaderImage {
124
124
  data: string;
@@ -168,6 +168,7 @@ export declare class DocumentReaderProcessor {
168
168
  }
169
169
 
170
170
  export declare interface DocumentReaderProcessParam {
171
+ generateNumericCodes?: boolean;
171
172
  returnPackageForReprocess?: boolean;
172
173
  returnUncroppedImage?: boolean;
173
174
  scenario?: InternalScenarios;
@@ -319,6 +320,8 @@ export declare interface DocumentTranslations {
319
320
  largeFile?: string;
320
321
  selectSmallerFile?: string;
321
322
  versionNotSupported?: string;
323
+ httpNotSupported?: string;
324
+ insecurePageContext?: string;
322
325
  updateBrowser?: string;
323
326
  licenseError?: string;
324
327
  licenseExpired?: string;
@@ -383,6 +386,7 @@ export declare enum EventActions {
383
386
  PRESS_SKIP_BUTTON = "PRESS_SKIP_BUTTON",
384
387
  PRESS_CAPTURE_BUTTON = "PRESS_CAPTURE_BUTTON",
385
388
  PRESS_CHANGE_CAMERA_BUTTON = "PRESS_CHANGE_CAMERA_BUTTON",
389
+ PRESS_REMOTE_DEVICE_BUTTON = "PRESS_REMOTE_DEVICE_BUTTON",
386
390
  PRESS_MIRRORING_BUTTON = "PRESS_MIRRORING_BUTTON",
387
391
  PRESS_CONNECT_BUTTON = "PRESS_CONNECT_BUTTON",
388
392
  PRESS_DISCONNECT_BUTTON = "PRESS_DISCONNECT_BUTTON",
@@ -398,7 +402,9 @@ export declare enum EventActions {
398
402
  FILE_PROCESS_STARTED = "FILE_PROCESS_STARTED",
399
403
  PROCESS_STARTED = "PROCESS_STARTED",
400
404
  PROCESS_FINISHED = "PROCESS_FINISHED",
401
- SERVICE_INITIALIZED = "SERVICE_INITIALIZED"
405
+ SERVICE_INITIALIZED = "SERVICE_INITIALIZED",
406
+ REMOTE_TRANSACTION_UPLOADED = "REMOTE_TRANSACTION_UPLOADED",
407
+ REMOTE_PROCESS_FINISHED = "REMOTE_PROCESS_FINISHED"
402
408
  }
403
409
 
404
410
  export declare enum FrameLineCap {
@@ -506,6 +512,7 @@ export declare interface PackageParams {
506
512
 
507
513
  export declare interface ProcessingRequest extends BaseRequest {
508
514
  metadata?: Record<string, any>;
515
+ delegateURL?: string;
509
516
  processParam: DocumentReaderProcessParam;
510
517
  imagesList?: Array<DocumentReaderImage>;
511
518
  imageInputParam?: ImageInputParamType;
@@ -542,11 +549,32 @@ declare type TProcessingListener = ({ isProcessing }: {
542
549
  isProcessing: boolean;
543
550
  }) => void;
544
551
 
552
+ export declare interface TransactionEvent {
553
+ action: EventActions.REMOTE_TRANSACTION_UPLOADED;
554
+ data: TransactionStatusInfo;
555
+ }
556
+
545
557
  export declare interface TransactionInfo {
546
558
  tag: string;
547
559
  transactionId: string;
548
560
  }
549
561
 
562
+ export declare type TransactionsListResponse = {
563
+ items: TransactionStatusInfo[];
564
+ };
565
+
566
+ export declare enum TransactionStateStatus {
567
+ STARTED = 0,
568
+ UPLOADED = 1,
569
+ PROCESSED = 2
570
+ }
571
+
572
+ export declare type TransactionStatusInfo = {
573
+ id: number;
574
+ state: TransactionStateStatus;
575
+ updatedAt: string;
576
+ };
577
+
550
578
  export declare type TScenarioParams = {
551
579
  name: string;
552
580
  desc: string;
@@ -584,11 +612,10 @@ export { }
584
612
 
585
613
  declare global {
586
614
  interface HTMLElementEventMap {
587
- 'document-reader': CustomEvent<DocumentReaderDetailType>;
615
+ 'document-reader': CustomEvent<DocumentReaderDetailType | TransactionEvent>;
588
616
  'camera-snapshot': CustomEvent<CameraSnapshotDetailType>;
589
617
  }
590
618
  interface Window {
591
619
  RegulaDocumentSDK: DocumentReaderService;
592
620
  }
593
621
  }
594
-