From ee29e772c9d312e2f50ce773fddcfd071d9602b8 Mon Sep 17 00:00:00 2001 From: DMGithubPublisher Date: Sat, 24 May 2025 06:13:11 +0800 Subject: [PATCH 1/3] update to internal commit 20965a62 chore: fix .gitignore feat: GitHub preview CI workflow chore: fix whitespace, EOF newline, and styling fix: formatting --- .github/workflows/main.yml | 18 +++-- .gitignore | 36 ++++++---- api/enums-mrz-scanner.md | 2 +- api/index.md | 10 +-- api/mrz-scanner.md | 6 +- codegallery/demo/index.md | 2 +- codegallery/helloworld/index.md | 4 +- codegallery/index.md | 2 +- gettingstarted/add_dependency.md | 102 ++++++++++++++++------------ gettingstarted/license.md | 2 +- gettingstarted/sys_requirement.md | 6 +- guides/mrz-scanner-customization.md | 15 +++- guides/mrz-scanner-static-image.md | 2 +- guides/mrz-scanner.md | 44 +++++++----- index.md | 14 ++-- introduction/index.md | 8 +-- releasenotes/index.md | 13 ++-- 17 files changed, 173 insertions(+), 113 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index a944516..481c59f 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -4,18 +4,18 @@ name: CI # Controls when the workflow will run on: - # Triggers the workflow on push events but only for the main branch + # Triggers the workflow on push events to the main and preview branches push: - branches: - - main - #- preview + branches: + - main + - preview # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # A workflow run is made up of one or more jobs that can run sequentially or in parallel jobs: - # This workflow contains jobs called "Build-Master" + # This workflow contains jobs called "Build-Main" and "Build-Preview" Build-Main: if: ${{ github.ref == 'refs/heads/main' }} uses: dynamsoft-docs/Docs-Template-Repo/.github/workflows/called-workflow-build-sync-production.yml@main @@ -23,3 +23,11 @@ jobs: doc-repo: mrz-scanner-docs-js doc-url: mrz-scanner/docs/web secrets: inherit + + Build-Preview: + if: ${{ github.ref == 'refs/heads/preview' }} + uses: dynamsoft-docs/Docs-Template-Repo/.github/workflows/called-workflow-build-sync-testing.yml@main + with: + doc-repo: mrz-scanner-docs-js + doc-url: mrz-scanner/docs/web + secrets: inherit diff --git a/.gitignore b/.gitignore index 056ca9e..8ac9b07 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,19 @@ .DS_Store /.vs -Gemfile -Hide_Tree_Page.md -sitemap.xml -_includes/productNav/* + +# Layout templates +_layouts/ + +# Assets +assets/font-face/ +assets/img-icon/ +assets/js/** +!assets/js/setLatestVersion.js +assets/scripts/ +assets/css/ + +# Includes +_includes/productNav/ _includes/auto-version-list.html _includes/head.html _includes/liquid_autoGenerateHistoryList.html @@ -18,12 +28,14 @@ _includes/productNav_OLD.html _includes/productNav.html _includes/search-input.html _includes/trialLicense.html -_layouts/* -_plugins/* -assets/css/* -assets/font-face/* -assets/img-icon/* -assets/js/* -assets/scripts/* -_site/* + +# Plugins +_plugins/ + +# Site resources +_site/ + +sitemap.xml +Hide_Tree_Page.md Gemfile.lock +Gemfile diff --git a/api/enums-mrz-scanner.md b/api/enums-mrz-scanner.md index 8364be0..2048ce7 100644 --- a/api/enums-mrz-scanner.md +++ b/api/enums-mrz-scanner.md @@ -56,4 +56,4 @@ enum EnumMRZData { DateOfBirth = "dateOfBirth", DateOfExpiry = "dateOfExpiry", } -``` \ No newline at end of file +``` diff --git a/api/index.md b/api/index.md index 3861291..2099a51 100644 --- a/api/index.md +++ b/api/index.md @@ -20,7 +20,7 @@ Please read through the [**full API reference**](mrz-scanner.md), but you can fi 2. MRZScannerView - Represents the main view of the MRZ Scanner where the scanning operation occurs. -3. MRZResultView - Displays the parsed MRZ result in human readable fields, along with a cropped image of the MRZ document. +3. MRZResultView - Displays the parsed MRZ result in human readable fields, along with a cropped image of the MRZ document. ## Interfaces @@ -32,11 +32,11 @@ Please read through the [**full API reference**](mrz-scanner.md), but you can fi 4. [MRZResultViewToolbarButtonsConfig](mrz-scanner.md#mrzresultviewtoolbarbuttonsconfig) - Configures the toolbar buttons of the **MRZResultView**. -4. [MRZResult](mrz-scanner.md#mrzresult) - Represents a typical MRZ result along with all of the parsed fields that come with it. +5. [MRZResult](mrz-scanner.md#mrzresult) - Represents a typical MRZ result along with all of the parsed fields that come with it. -5. [MRZData](mrz-scanner.md#mrzdata) - Represents the parsed MRZ data that is part of the `MRZResult`. +6. [MRZData](mrz-scanner.md#mrzdata) - Represents the parsed MRZ data that is part of the `MRZResult`. -6. [MRZDate](mrz-scanner.md#mrzdate) - Represents a date in the MRZ fields - which is usually used for date of birth and the date of expiry. +7. [MRZDate](mrz-scanner.md#mrzdate) - Represents a date in the MRZ fields - which is usually used for date of birth and the date of expiry. ## Enumerations @@ -46,4 +46,4 @@ All of the enumerations can be found [**here**](enums-mrz-scanner.md). Here is a 2. [EnumResultStatus](enums-mrz-scanner.md#enumresultstatus) - An enumeration to represent the status of a MRZ result. -3. [EnumMRZData](enums-mrz-scanner.md) - An enumeration to represent the different fields of the `MRZData` interface. \ No newline at end of file +3. [EnumMRZData](enums-mrz-scanner.md) - An enumeration to represent the different fields of the `MRZData` interface. diff --git a/api/mrz-scanner.md b/api/mrz-scanner.md index 0132831..0242798 100644 --- a/api/mrz-scanner.md +++ b/api/mrz-scanner.md @@ -115,7 +115,7 @@ To get the full picture on how to use *MRZScannerConfig*, please visit the [Cust ```ts interface MRZScannerConfig { license?: string; // license is absolutely required to be set at initialization - container?: HTMLElement | string; // + container?: HTMLElement | string; // // Resource/Template specific configuration templateFilePath?: string; @@ -152,7 +152,7 @@ const mrzConfig = { license: "YOUR_LICENSE_KEY_HERE", mrzFormatType: ["passport", "td1"], // set the MRTD formats to just passport and ID (TD1) showResultView: false, // hide the final MRZResultView and go back to landing page once the MRZ result is in - // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference + // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference engineResourcePaths: { std: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std/dist/", dip: "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing/dist/", @@ -504,4 +504,4 @@ type ResultStatus = { #### Example -Please see the [example of MRZResult](#example-8). \ No newline at end of file +Please see the [example of MRZResult](#example-8). diff --git a/codegallery/demo/index.md b/codegallery/demo/index.md index 9656ec9..a44f884 100644 --- a/codegallery/demo/index.md +++ b/codegallery/demo/index.md @@ -38,4 +38,4 @@ For the best demonstration of the full capabilities of the MRZ Scanner JavaScrip If you do not wish to build the library from the source files, you can change the script reference at the `` of the code to the CDN link. To learn more about the ways you can include the library, please visit [User Guide - Quick Start]({{ site.guides }}mrz-scanner.html#quick-start---hello-world). -To learn how you can further customize the MRZ Scanner in your code, please visit [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html). \ No newline at end of file +To learn how you can further customize the MRZ Scanner in your code, please visit [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html). diff --git a/codegallery/helloworld/index.md b/codegallery/helloworld/index.md index c5845ed..94d4ef3 100644 --- a/codegallery/helloworld/index.md +++ b/codegallery/helloworld/index.md @@ -36,7 +36,7 @@ Hello World represents the most basic implementation of the MRZ Scanner. One of }); (async () => { // Launch the scanner and wait for the result - const result = await mrzScanner.launch({}); + const result = await mrzScanner.launch(); })(); @@ -55,4 +55,4 @@ The simplest implementation means that the MRZ Scanner is initialized with the d For a further breakdown of the Hello World code, please visit the [User Guide]({{ site.guides }}mrz-scanner.html). -To learn how to customize the scanner to fit your needs, please visit [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html). \ No newline at end of file +To learn how to customize the scanner to fit your needs, please visit [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html). diff --git a/codegallery/index.md b/codegallery/index.md index 9b0896f..3fe6e68 100644 --- a/codegallery/index.md +++ b/codegallery/index.md @@ -50,4 +50,4 @@ The demo implementation adds a bit more colour and character to the Hello World The full code of the Demo can be found [**here**](demo/index.md). -For the best demonstration of the full capabilities of the MRZ Scanner JavaScript Edition, please visit the [official Dynamsoft MRZ Scanner JavaScript demo](https://demo.dynamsoft.com/mrz-scanner/). \ No newline at end of file +For the best demonstration of the full capabilities of the MRZ Scanner JavaScript Edition, please visit the [official Dynamsoft MRZ Scanner JavaScript demo](https://demo.dynamsoft.com/mrz-scanner/). diff --git a/gettingstarted/add_dependency.md b/gettingstarted/add_dependency.md index 91cedcb..a03e687 100644 --- a/gettingstarted/add_dependency.md +++ b/gettingstarted/add_dependency.md @@ -53,6 +53,7 @@ Besides using the CDN, you can also download the SDKs and host related files on **Step 1** - Download the SDKs: {% comment %} + - From the website [Download the JavaScript ZIP package](https://www.dynamsoft.com/mobile-web-capture/downloads/) @@ -69,7 +70,8 @@ Besides using the CDN, you can also download the SDKs and host related files on yarn add dynamsoft-image-processing@2.2.10 yarn add dynamsoft-camera-enhancer@4.0.2 ``` -{% endcomment %} + + {% endcomment %} - npm @@ -84,31 +86,31 @@ Besides using the CDN, you can also download the SDKs and host related files on npm install dynamsoft-camera-enhancer@4.0.2 ``` - - **Step 2** - Include the SDKs Depending on where you put them, you can typically include them like this: {% comment %} - ```html - - - - - - - ``` + +```html + + + + + + +``` or {% endcomment %} - ```html - - - - - - - ``` + +```html + + + + + + +``` **Step 3** Specify the location of the engine files(optinal) @@ -116,31 +118,47 @@ If you would like to use the SDKs completely offline, please refer to [Use your ## Specify the location of the engine files -This is usually only required with frameworks like Angular or React, etc. where the referenced JavaScript files such as cvr.js, ddn.js are compiled into another file, or hosting the engine files and using the SDKs completely offline. The purpose is to tell the SDK where to find the engine files (*.worker.js, *.wasm.js and *.wasm, etc.). +This is usually only required with frameworks like Angular or React, etc. where the referenced JavaScript files such as cvr.js, ddn.js are compiled into another file, or hosting the engine files and using the SDKs completely offline. The purpose is to tell the SDK where to find the engine files (_.worker.js, _.wasm.js and \*.wasm, etc.). ### Use the jsDelivr CDN with frameworks like Angular or React, etc. - ```typescript - Dynamsoft.DDV.Core.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-document-viewer@2.0.0/dist/engine"; - Dynamsoft.Core.CoreModule.engineResourcePaths.core = "https://cdn.jsdelivr.net/npm/dynamsoft-core@3.2.10/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.license = "https://cdn.jsdelivr.net/npm/dynamsoft-license@3.2.10/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.ddn = "https://cdn.jsdelivr.net/npm/dynamsoft-document-normalizer@2.2.10/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.cvr = "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router@2.2.10/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.std = "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std@1.2.0/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.dip = "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing@2.2.10/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.dce = "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@4.0.2/dist/"; - ``` + +```typescript +Dynamsoft.DDV.Core.engineResourcePath = + "https://cdn.jsdelivr.net/npm/dynamsoft-document-viewer@2.0.0/dist/engine"; +Dynamsoft.Core.CoreModule.engineResourcePaths.core = + "https://cdn.jsdelivr.net/npm/dynamsoft-core@3.2.10/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.license = + "https://cdn.jsdelivr.net/npm/dynamsoft-license@3.2.10/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.ddn = + "https://cdn.jsdelivr.net/npm/dynamsoft-document-normalizer@2.2.10/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.cvr = + "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router@2.2.10/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.std = + "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std@1.2.0/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dip = + "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing@2.2.10/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dce = + "https://cdn.jsdelivr.net/npm/dynamsoft-camera-enhancer@4.0.2/dist/"; +``` ### Use your own hosted engine files - ```typescript - //Feel free to change it to your own location of these files - Dynamsoft.DDV.Core.engineResourcePath = "./node_modules/dynamsoft-document-viewer/dist/engine"; - Dynamsoft.Core.CoreModule.engineResourcePaths.core = "./node_modules/dynamsoft-core/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.license = "./node_modules/dynamsoft-license/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.ddn = "./node_modules/dynamsoft-document-normalizer/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.cvr = "./node_modules/dynamsoft-capture-vision-router/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.std = "./node_modules/dynamsoft-capture-vision-std/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.dip = "./node_modules/dynamsoft-image-processing/dist/"; - Dynamsoft.Core.CoreModule.engineResourcePaths.dce = "./node_modules/dynamsoft-camera-enhancer/dist/"; - ``` - \ No newline at end of file +```typescript +//Feel free to change it to your own location of these files +Dynamsoft.DDV.Core.engineResourcePath = + "./node_modules/dynamsoft-document-viewer/dist/engine"; +Dynamsoft.Core.CoreModule.engineResourcePaths.core = + "./node_modules/dynamsoft-core/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.license = + "./node_modules/dynamsoft-license/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.ddn = + "./node_modules/dynamsoft-document-normalizer/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.cvr = + "./node_modules/dynamsoft-capture-vision-router/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.std = + "./node_modules/dynamsoft-capture-vision-std/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dip = + "./node_modules/dynamsoft-image-processing/dist/"; +Dynamsoft.Core.CoreModule.engineResourcePaths.dce = + "./node_modules/dynamsoft-camera-enhancer/dist/"; +``` diff --git a/gettingstarted/license.md b/gettingstarted/license.md index fe79929..96230f1 100644 --- a/gettingstarted/license.md +++ b/gettingstarted/license.md @@ -29,4 +29,4 @@ The following code snippet is using the public trial license to initialize the l const mrzScanner = new Dynamsoft.MRZScanner({ license: "YOUR_LICENSE_KEY_HERE", }); -``` \ No newline at end of file +``` diff --git a/gettingstarted/sys_requirement.md b/gettingstarted/sys_requirement.md index 2f63797..2c0c2d0 100644 --- a/gettingstarted/sys_requirement.md +++ b/gettingstarted/sys_requirement.md @@ -17,10 +17,10 @@ The MRZ Scanner JavaScript Edition solution is built upon the JavaScript edition 1. **Secure context (HTTPS deployment)** When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons - + - Access to the camera video stream is only granted in a security context. Most browsers impose this restriction. > Some browsers like Chrome may grant the access for `http://127.0.0.1` and `http://localhost` or even for pages opened directly from the local disk (`file:///...`). This can be helpful for temporary development and testing. - + - Dynamsoft licenses require a secure context to work, unless a special offline license is used. 2. **`WebAssembly`, `Blob`, `URL`/`createObjectURL`, `Web Workers`** @@ -47,4 +47,4 @@ Apart from the browsers, the operating systems may impose some limitations of th ## References - [Dynamsoft Label Recognizer - System Requirements](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/user-guide/mrz-scanner.html#system-requirements) -- [Dynamsoft Code Parser - System Requirements](https://www.dynamsoft.com/code-parser/docs/web/programming/javascript/user-guide/#system-requirements) \ No newline at end of file +- [Dynamsoft Code Parser - System Requirements](https://www.dynamsoft.com/code-parser/docs/web/programming/javascript/user-guide/#system-requirements) diff --git a/guides/mrz-scanner-customization.md b/guides/mrz-scanner-customization.md index 5041f88..5359a61 100644 --- a/guides/mrz-scanner-customization.md +++ b/guides/mrz-scanner-customization.md @@ -15,6 +15,17 @@ permalink: /guides/mrz-scanner-customization.html > >Before going into the ways that you can customize the MRZ Scanner, please read the [MRZ Scanner JavaScript Edition User Guide]({{ site.guides }}mrz-scanner.html). +## Quick Links + +- [Setting Available MRTD formats](#setting-available-mrtd-formats) +- [Hiding the Result View](#hiding-the-result-view) +- [Changing the Scan Guide Frame](#changing-the-scan-guide-frame) +- [Reading Static Images and PDFs using the MRZ Scanner](#reading-static-images-and-pdfs-using-the-mrz-scanner) +- [Configuring the `onDone` Callback](#configuring-the-ondone-callback) +- [Enable Result Editing](#enable-result-editing) + +## Introduction + This guide expands on the User Guide that explored the MRZ Scanner Hello World sample project. Here we explore ways to customize the UI as well as the performance of the MRZ Scanner. We will walk through the three main configuration interfaces - [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig), [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), and [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig). These configuration interfaces make customizing the MRZ Scanner as easy as adding or changing a few properties in the instance constructor. Every sample is a variation on the previous Hello World sample with a few additional properties defined in the configuration interfaces, and so we only show the differing portion rather than all the code. ## `MRZScannerConfig` Overview @@ -146,9 +157,9 @@ The `MRZScannerView` provides a guide frame for each of the three MRTD formats. Please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) for any further inquiries, or to customize the frame guide selection logic. -### Reading Static Images using the MRZ Scanner +### Reading Static Images and PDFs using the MRZ Scanner -Starting from v2.1 of the MRZ Scanner, the library is now able to read MRZs **directly** from static images and PDFs. To support this, the MRZScannerViewConfig will need to be configured to support that, especially for PDFs. +Starting from **v2.1** of the MRZ Scanner, the library is now able to read MRZs **directly** from static images and PDFs. To support this, the MRZScannerViewConfig will need to be configured to support that, especially for PDFs. To learn more on how to create a web application that supports static image/PDF reading using the MRZ Scanner, please refer to this [guide]({{ site.guides }}mrz-scanner-static-image.html). Furthermore, please refer to the full File Input Sample that the previously linked guide walks you through. diff --git a/guides/mrz-scanner-static-image.md b/guides/mrz-scanner-static-image.md index 77d2950..9e0e84e 100644 --- a/guides/mrz-scanner-static-image.md +++ b/guides/mrz-scanner-static-image.md @@ -35,7 +35,7 @@ The first step in making the sample is to define the script references and the H Dynamsoft MRZ Scanner - Use File Input - + diff --git a/guides/mrz-scanner.md b/guides/mrz-scanner.md index 98211b2..bb479e3 100644 --- a/guides/mrz-scanner.md +++ b/guides/mrz-scanner.md @@ -91,7 +91,7 @@ Below is the complete Hello World sample page that uses the precompiled script s }); (async () => { // Launch the scanner and wait for the result - const result = await mrzScanner.launch({}); + const result = await mrzScanner.launch(); })(); @@ -100,8 +100,8 @@ Below is the complete Hello World sample page that uses the precompiled script s > [!NOTE] > -> This code is identical to the Hello World file mentioned in *Build from Source*, except for the script source. -> +> This code is a more simplified version of the Hello World file that is hosted on [Github](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/samples/hello-world.html). +> The file hosted on Github contains more code for a better final UI, but that extra code is not necessary to successfully launching the MRZ Scanner. All you need is the code shown above. > Please do not forget to replace `YOUR_LICENSE_KEY_HERE` with your own license key, whether it is trial or full. To run the sample, create a new file called `hello-world.html`, then copy and paste the code above into the file. Next, serve the page directly by deploying it to a server. @@ -176,30 +176,40 @@ The first step in setting up the HTML in the Hello World project is to include t MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it creates a container which it populates with the **Ready-to-Use UI**. - - ### Step 2: Initializing the MRZ Scanner -```js -// Initialize the Dynamsoft MRZ Scanner -const mrzscanner = new Dynamsoft.MRZScanner({ - license: "YOUR_LICENSE_KEY_HERE", -}); +```html + +

Dynamsoft MRZ Scanner

+ + + ``` Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. ### Step 3: Launching the MRZ Scanner -```js -(async () => { - // Launch the scanner and wait for the result - const result = await mrzscanner.launch({}); - console.log(result); -})(); +```html + ``` -Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`** , which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: +Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: #### `MRZScannerView` diff --git a/index.md b/index.md index 1215a3d..faab994 100644 --- a/index.md +++ b/index.md @@ -9,13 +9,13 @@ description: MRZ Scanner JavaScript Edition Documentation Homepage - [Introduction]({{ site.introduction }}index.html) - Developer Guides - - [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html) - - [MRZ Scanner Customization Guide]({{ site.guides }}mrz-scanner-customization.html) - - [MRZ Scanner - Reading from Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) + - [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html) + - [MRZ Scanner Customization Guide]({{ site.guides }}mrz-scanner-customization.html) + - [MRZ Scanner - Reading from Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) - Getting Started - - [System Requirements]({{ site.gettingstarted }}sys_requirement.html) - - [Dependencies]({{ site.gettingstarted }}add_dependency.html) - + - [System Requirements]({{ site.gettingstarted }}sys_requirement.html) + - [Dependencies]({{ site.gettingstarted }}add_dependency.html) + - [Code Gallery]({{ site.codegallery }}index.html) - [API Reference]({{ site.api }}index.html) -- [Release Notes]({{ site.releasenotes }}index.html) \ No newline at end of file +- [Release Notes]({{ site.releasenotes }}index.html) diff --git a/introduction/index.md b/introduction/index.md index a26ec07..40ec9d3 100644 --- a/introduction/index.md +++ b/introduction/index.md @@ -66,7 +66,7 @@ In some more rare cases, an ID card can have a MRZ that conforms to the **TD2** We designed the **MRZ Scanner JavaScript Edition** with three core principles in mind: -1. **Minimal Code** - High-level API provide full recognition and parsing functionality with **just a few lines of code**, significantly reducing development and maintenance costs. +1. **Minimal Code** - High-level API provide full recognition and parsing functionality with **just a few lines of code**, significantly reducing development and maintenance costs. 2. **Ready-To-Use UI** - Pre-integrated components and a pre-designed UI simplify the process even more for any developer, enabling a **quick setup and saving any time and effort needed for the UI design**. 3. **Effortless Customization** - Tailored configuration interfaces allow for **quick and simple customization** of the scanner settings and performance. @@ -78,7 +78,7 @@ The **MRZ Scanner JavaScript Edition** is reliant on two core views, the **`MRZS #### `MRZScannerView` -The **`MRZScannerView`** is the main view of the solution which displays the camera view, along with some UI elements that control the scanner and camera settings, along with icons to allow the user to load in a photo from the photo library as well as close the scanner. This view comes with a scan guide frame in the center to better guide the user on where to place the MRZ document for best results. +The **`MRZScannerView`** is the main view of the solution which displays the camera view, along with some UI elements that control the scanner and camera settings, along with icons to allow the user to load in a photo from the photo library as well as close the scanner. This view comes with a scan guide frame in the center to better guide the user on where to place the MRZ document for best results. Here is a quick screenshot at default look of the **`MRZScannerView`**: @@ -88,7 +88,7 @@ Here is a quick screenshot at default look of the **`MRZScannerView`**: #### `MRZResultView` -The **`MRZResultView`** is responsible for displaying the final parsed results of the MRZ recognition process. The final parsed results, along with their corresponding field names, appear as a scrollable form view underneath the original image of the MRZ document. +The **`MRZResultView`** is responsible for displaying the final parsed results of the MRZ recognition process. The final parsed results, along with their corresponding field names, appear as a scrollable form view underneath the original image of the MRZ document. Included with those two things are two buttons, one that allows the user to scan again if needed, and the other to wrap up the scanning process and proceed to the next step (like navigating to another page). @@ -137,4 +137,4 @@ For the best demonstration of the full capabilities of the MRZ Scanner JavaScrip ## Next Steps -If you are looking to create your own MRZ scanning application for browsers, then the **MRZ Scanner JavaScript Edition** is the solution for you! To get started with the development, please refer to the [**User Guide**]({{ site.guides }}mrz-scanner.html) that will walk you through the steps to get a *Hello World* implementation going as well as the different ways you can customize the **MRZ Scanner**. \ No newline at end of file +If you are looking to create your own MRZ scanning application for browsers, then the **MRZ Scanner JavaScript Edition** is the solution for you! To get started with the development, please refer to the [**User Guide**]({{ site.guides }}mrz-scanner.html) that will walk you through the steps to get a *Hello World* implementation going as well as the different ways you can customize the **MRZ Scanner**. diff --git a/releasenotes/index.md b/releasenotes/index.md index 9e43cc8..3d30ccb 100644 --- a/releasenotes/index.md +++ b/releasenotes/index.md @@ -16,14 +16,14 @@ permalink: /releasenotes/index.html ## Highlighted Features -- **[UI]** Redesigned the *MRZScannerView* (the main camera view) to have updated icons and better alignment and spacing. +- **[UI]** Redesigned the **`MRZScannerView`** (the main camera view) to have updated icons and better alignment and spacing. - Changed the default camera resolution when the camera is opened from **1080p** to **2K** (if the camera supports it). -- Added a new property to the *MRZScannerViewConfig* interface, **showPoweredByDynamsoft**, which controls the visibility of the `Powered By Dynamsoft` message that is part of the *MRZScannerView* UI. -- Introduced the ability for the MRZ Scanner to read MRZs from static images and PDFs without the need to use the *MRZScannerView* UI and the Load Image button. -- Added two new properties to the *MRZScannerViewConfig* interface, **uploadAcceptedTypes** and **uploadFileConverter**, which convert static images and PDFs to blobs which can then be read by the MRZ Scanner. +- Added a new property to the **`MRZScannerViewConfig`** interface, **`showPoweredByDynamsoft`**, which controls the visibility of the `Powered By Dynamsoft` message that is part of the **`MRZScannerView`** UI. +- Introduced the ability for the MRZ Scanner to read MRZs from static images and PDFs without the need to use the **`MRZScannerView`** UI and the Load Image button. +- Added two new properties to the **`MRZScannerViewConfig`** interface, **`uploadAcceptedTypes`** and **`uploadFileConverter`**, which convert static images and PDFs to blobs which can then be read by the MRZ Scanner. - Redeveloped the `launch()` method so that it can take a static image or file as input. To learn how to use that, please refer to [Setting up the MRZ Reader for Static Images]({{ site.guides }}mrz-scanner-static-image.html) - Integrated Dynamsoft's [Mobile Web Capture](https://www.dynamsoft.com/mobile-web-capture/docs/introduction/) with the MRZ Scanner (JavaScript Edition) to allow the user to edit the scanned MRZ image like a document. -- Added `NationalityRaw` and `IssuingStateRaw` to the `MRZData` interface that represent the raw values of these fields +- Added `NationalityRaw` and `IssuingStateRaw` to the `MRZData` interface that represent the raw values of these fields ## Fixes @@ -47,6 +47,7 @@ The **MRZ Scanner JavaScript Edition** has been redesigned and redeveloped to no MRZ Scanner JavaScript Edition is organized into configurable UI views. Below is a quick overview of the two main views: +> [!TIP] > Learn more about these views and how to configure them in the [User Guide]({{ site.guides }}mrz-scanner.html) and the [Customization Guide]({{ site.guides }}mrz-scanner-customization.html). ### MRZ Scanner View @@ -63,4 +64,4 @@ MRZ Scanner JavaScript Edition is organized into configurable UI views. Below is - Scrollable field view to display the parsed MRZ info - Displays the original image of the MRZ document - Allows the user to edit almost all of the parsed fields -- Two buttons to allow the user to re-scan or move on \ No newline at end of file +- Two buttons to allow the user to re-scan or move on From 081a0771bf6e03ac1178804a547b3d4d93636ca9 Mon Sep 17 00:00:00 2001 From: Amro-Dynamsoft Date: Tue, 17 Jun 2025 15:39:58 -0700 Subject: [PATCH 2/3] Staging for v3 of MRZ Scanner (#15) * update to internal commit 20965a62 * chore: fix .gitignore * feat: GitHub preview CI workflow * chore: fix whitespace, EOF newline, and styling * fix: formatting * v3 deployment All the docs have been updated to v3. What is left will be to fix the versioning for 2.0 and 2.1 --------- Co-authored-by: DMGithubPublisher <65145280+DMGithubPublisher@users.noreply.github.com> Co-authored-by: Justin-Dynamsoft <33125453+a362758199@users.noreply.github.com> Co-authored-by: Tom Kent Co-authored-by: Amro Anwer Co-authored-by: DMGithubPublisher Co-authored-by: dynamsoft-h <172081603+dynamsoft-h@users.noreply.github.com> --- api/mrz-scanner-v2.0.md | 474 ++++++++++++++++++++++++++++ api/mrz-scanner.md | 40 ++- codegallery/helloworld/index.md | 2 +- guides/mrz-scanner-customization.md | 4 +- guides/mrz-scanner-static-image.md | 2 +- guides/mrz-scanner-v2.0.md | 265 ++++++++++++++++ guides/mrz-scanner-v2.1.md | 265 ++++++++++++++++ guides/mrz-scanner.md | 56 +++- releasenotes/index.md | 15 + 9 files changed, 1103 insertions(+), 20 deletions(-) create mode 100644 api/mrz-scanner-v2.0.md create mode 100644 guides/mrz-scanner-v2.0.md create mode 100644 guides/mrz-scanner-v2.1.md diff --git a/api/mrz-scanner-v2.0.md b/api/mrz-scanner-v2.0.md new file mode 100644 index 0000000..6450b14 --- /dev/null +++ b/api/mrz-scanner-v2.0.md @@ -0,0 +1,474 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition - API Reference +keywords: Documentation, MRZ Scanner JavaScript Edition, API, APIs +breadcrumbText: API References +description: Dynamsoft MRZ Scanner JavaScript Edition - API Reference +--- + +# MRZ Scanner JavaScript Edition API Reference + +The `MRZScanner` class is responsible for the main scanning process, including MRZ recognition, text parsing, and result display. + +## Constructor + +### MRZScanner + +#### Syntax + +```ts +new MRZScanner(config: MRZScannerConfig) +``` + +#### Parameters + +- `config`: Assigns the MRZ Scanner license and configures the different settings of the MRZ Scanner, including the container, supported MRTD formats, and more. This config object is of type [*MRZScannerConfig*](#mrzscannerconfig). + +#### Example + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + // For custom scanning configuration, MRZScannerViewConfig goes in here + }, + resultViewConfig: { + // For custom result configuration, MRZResultViewConfig goes in here + } +}); +``` + +## Methods + +### launch() + +Starts the **MRZ scanning workflow**. If the method is run without a file input, the MRZScannerView UI will pop up and allow the user to scan MRZs using their camera. Alternatively, if the method is run with a file input parameter, the MRZ Scanner will read the MRZ from the file and display the result in a `MRZResultView`. + +#### Syntax + +```ts +launch(): Promise +``` + +#### Returns + +A `Promise` resolving to a `MRZResult` object. + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + try { + const result = await mrzScanner.launch(); + console.log(result); // print the MRZResult to the console + } catch (error){ + console.error(error); + } +})(); +``` + +### dispose() + +Cleans up the MRZ Scanner resources and hides UI components. + +#### Syntax + +```ts +dispose(): void +``` + +#### Example + +```ts +mrzScanner.dispose(); +console.log("Scanner resources released."); +``` + +## Configuration Interfaces + +### MRZScannerConfig + +The **MRZScannerConfig** is responsible for assigning the MRZ Scanner license, configuring the MRTD formats, and setting the MRZScannerViewConfig and MRZResultViewConfig. Please note that the only thing that is **required** to be defined is the **license**. A MRZ Scanner instance **must** be initialized with a MRZScannerConfig object. + +To get the full picture on how to use *MRZScannerConfig*, please visit the [Customizing MRZ Scanner - MRZScannerConfig]({{ site.guides }}mrz-scanner-customization.html#mrzscannerconfig-overview) page. + +#### Syntax + +```ts +interface MRZScannerConfig { + license?: string; // license is absolutely required to be set at initialization + container?: HTMLElement | string; // + + // Resource/Template specific configuration + templateFilePath?: string; + utilizedTemplateNames?: UtilizedTemplateNames; + engineResourcePaths?: EngineResourcePaths; + + // Views Configuration + scannerViewConfig?: Omit; + resultViewConfig?: MRZResultViewConfig; + + mrzFormatType?: Array; + showResultView?: boolean; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `license` | `string` | The license key for using the `MRZScanner`. | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZScanner` UI. | +| `templateFilePath` | `string` | The file path to the custom JSON template used to customize the scanning process. | +| `utilizedTemplateNames` | `UtilizedTemplateNames` | Specifies MRZ scanning templates. | +| `engineResourcePaths` | `EngineResourcePaths` | Paths to the necessary resources for the MRZ scanning engine. | +| `scannerViewConfig` | `MRZScannerViewConfig` | Configuration settings for the MRZ scanner view. | +| `resultViewConfig` | `MRZResultViewConfig` | Configuration settings for the MRZ result view. | +| `mrzFormatType` | [`EnumMRZDocumentType`]({{ site.api }}enums-mrz-scanner.html#enummrzdocumenttype) | Specifies the MRTD formats that the application will support. | +| `showResultView` | `boolean` | Determines whether the final result view (MRZResultView) will be shown or not. | + +#### Example + +```ts +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + mrzFormatType: ["passport", "td1"], // set the MRTD formats to just passport and ID (TD1) + showResultView: false, // hide the final MRZResultView and go back to landing page once the MRZ result is in + // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference + engineResourcePaths: { + std: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std/dist/", + dip: "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing/dist/", + core: "https://cdn.jsdelivr.net/npm/dynamsoft-core/dist/", + license: "https://cdn.jsdelivr.net/npm/dynamsoft-license/dist/", + cvr: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router/dist/", + dlr: "https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer/dist/", + dcp: "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser/dist/", + }, + scannerViewConfig: { + // the MRZScannerViewConfig goes in here - see MRZScannerViewConfig section + }, + resultViewConfig: { + // the MRZResultViewConfig goes in here - see MRZResultViewConfig section + } +}; + +// Initialize the Dynamsoft MRZ Scanner with the above MRZScannerConfig object +const mrzScanner = new Dynamsoft.MRZScanner(mrzConfig); +``` + +### MRZScannerViewConfig + +The MRZScannerViewConfig is used to configure the UI elements of the **MRZScannerView**. If the MRZScannerViewConfig is not assigned, then the library will use the default MRZScannerView. For the full details of the properties of the MRZScannerViewConfig, please read through the [Customizing the MRZ Scanner - MRZScannerViewConfig]({{ site.guides }}mrz-scanner-customization.html#mrzscannerviewconfig-overview) page. + +#### Syntax + +```ts +interface MRZScannerViewConfig { + cameraEnhancerUIPath?: string; + container?: HTMLElement | string; + + showScanGuide?: boolean; + showUploadImage?: boolean; + showFormatSelector?: boolean; + showSoundToggle?: boolean; + + enableMultiFrameCrossFilter?: boolean; // false by default +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `cameraEnhancerUIPath` | `string` | Path to the custom Camera Enhancer UI (`.html` template file) for the scanner view. | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZScannerView` UI. | +| `showScanGuide` | `boolean` | Determines whether the scan guide frame will be displayed or not. | +| `showUploadImage` | `boolean` | Determines the visibility of the "load image" icon to allow the user to select a static image from their local photo library. | +| `showFormatSelector` | `boolean` | Determines the visibility of the format selector box that allows the user to restrict the MRTD format(s) that are being read. | +| `showSoundToggle` | `boolean` | Determines the visibility of the "sound" icon that allows the user to play a beep sound once the MRZ is recognized. | +| `enableMultiFrameCrossFilter` | `boolean` | Enables or disables the MultiFrameResultCrossFilter that can improve the accuracy of the MRZ result, but possibly at the cost of speed. | + +#### Example + +```ts +const mrzScanViewConfig = { + showScanGuide: true, // hides the scan guide frame; true by default + showUploadImage: true, // hides the load image icon that shows up in the toolbar at the top of the view; true by default + showFormatSelector: true, // hides the format selector box if more than two MRZ types are assigned; true by default + showSoundToggle: false, // hides the sound icon that allows the user to control whether a beep is played once an MRZ is recognized; true by default + showPoweredByDynamsoft?: boolean; // hides the "Powered By Dynamsoft" message that appears on the scanner UI; true by default + + enableMultiFrameCrossFilter: true, // turning the filter off could improve the speed but at the cost of result accuracy; true by default +}; + +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: mrzScanViewConfig +}; +``` + +### MRZResultViewConfig + +The MRZResultViewConfig is used to configure the UI elements of the **MRZResultView**. If the MRZResultViewConfig is not assigned, then the library will use the default MRZResultView. For the full details of the properties of the MRZResultViewConfig, please read through the [Customizing the MRZ Scanner - MRZResultViewConfig]({{ site.guides }}mrz-scanner-customization.html#mrzresultviewconfig-overview) page. + +#### Syntax + +```ts +interface MRZResultViewConfig { + container?: HTMLElement | string; + toolbarButtonsConfig?: MRZResultViewToolbarButtonsConfig; + showOriginalImage?: boolean; + allowResultEditing?: boolean; // New option to control if result fields can be edited + + onDone?: (result: MRZResult) => Promise; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZResultView` UI. | +| `toolbarButtonsConfig` | `MRZResultViewToolbarButtonsConfig` | Configures the main bottom toolbar of the result view. | +| `showOriginalImage` | `boolean` | Determines whether the cropped image of the MRZ document will be displayed in the result view or not. | +| `allowResultEditing` | `boolean` | Enables/disables the ability to edit the MRZ info after it is scanned. | +| `onDone` | `Promise` | Defines the action(s) to take once the user clicks the "Done" button in the result view. | + +#### Example + +```ts +const mrzResultViewConfig = { + showOriginalImage: false, // Hides the cropped image of the MRZ document in the result view; true by default + toolbarButtonsConfig: { + retake: { + label: "Re-scan", // Changes the text label of the retake button to "Re-scan"; string is "Re-take" by default + isHidden: true // Hides the retake button; false by default + }, + done: { + label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default + isHidden: false // Hides the done button; false by default + } + }, + /* onDone is a callback that allows you to define the action(s) to take once the user clicks the Done button and the scanner is closed. By default, nothing happens and the app goes back to the landing page. */ + onDone: (result) => { + console.log(result.status.message); + console.log(result.data.firstName); + } +}; + +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + resultViewConfig: mrzResultViewConfig +}; +``` + +### MRZResultViewToolbarButtonsConfig + +The `MRZResultViewToolbarButtonsConfig` is used to configure the buttons of the toolbar in the **MRZResultView**. + +#### Syntax + +```ts +interface MRZResultViewToolbarButtonsConfig { + retake?: ToolbarButtonConfig; + done?: ToolbarButtonConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `retake` | `ToolbarButtonConfig` | Configuration for the re-scan button of the toolbar. | +| `done` | `ToolbarButtonConfig` | Configuration for the done button of the toolbar. | + +#### Example + +```ts +const mrzButtonConfig = { + retake: { + label: "Re-scan", + isHidden: false + }, + done: { + label: "Return Home", + isHidden: false + } +}; + +const mrzResultViewConfig = { + toolbarButtonsConfig: mrzButtonConfig, +}; +``` + +### ToolbarButtonConfig + +The interface used to configure the properties of the toolbar button. This interface is typically used in conjunction with the `MRZResultViewToolbarButtonsConfig`. + +#### Syntax + +```ts +export interface ToolbarButtonConfig { + icon: string; + label: string; + className?: string; + isHidden?: boolean; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `icon` | `string` | The path to a custom icon (png/svg) for the button. | +| `label` | `string` | The text label of the button. | +| `className` | `string` | Assigns a custom class to the button (usually to apply custom styling). | +| `isHidden` | `boolean` | Hides/Shows the button in the toolbar. | + +#### Example + +See the [example of `MRZResultViewToolbarButtonsConfig`](#example-6). + +## Result Interfaces + +### MRZResult + +The MRZResult is the most basic interface that is used to represent the full MRZ result object. It comes with a result status, the original cropped image result, and the parsed MRZ info as a [`MRZData`](#mrzdata) object. + +#### Syntax + +```ts +export interface MRZResult { + status: ResultStatus; + originalImageResult?: DSImageData; + data?: MRZData; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `status` | [`ResultStatus`](#resultstatus) | The status of the MRZ result, which can be successful, cancelled (if the user closes the scanner), or failed (indicating that something has gone wrong during the scanning process). | +| `originalImageResult` | [`DSImageData`]({{ site.dcvb_js_api }}core/basic-structures/ds-image-data.html) | A `DSImageData` object that represents the cropped image of the MRZ document. | +| `data` | [`MRZData`](#mrzdata) | Represents the parsed MRZ info. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.status.message); // prints the result status message to the console + console.log(result.status.code); // prints the result status code to the console + console.log(result.data); // prints the entire MRZData object of the result to the console +})(); +``` + +### MRZData + +MRZData is used to represent the parsed fields of the MRZ result. These fields include the first name, last name, sex, document number, and more. + +#### Syntax + +```ts +export interface MRZData { + [EnumMRZData.InvalidFields]?: EnumMRZData[]; //invalidFields + [EnumMRZData.DocumentType]: string; // documentType + [EnumMRZData.DocumentNumber]: string; // documentNumber + [EnumMRZData.MRZText]: string; // mrzText + [EnumMRZData.FirstName]: string; // firstName + [EnumMRZData.LastName]: string; // lastName + [EnumMRZData.Age]: number; // age + [EnumMRZData.Sex]: string; // sex + [EnumMRZData.IssuingState]: string; // issuingState + [EnumMRZData.Nationality]: string; // nationality + [EnumMRZData.DateOfBirth]: MRZDate; // dateOfBirth + [EnumMRZData.DateOfExpiry]: MRZDate; // dateOfExpiry +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `documentType` | `string` | The type of MRTD that the MRZ document is. | +| `documentNumber` | `string` | The MRZ document number. | +| `mrzText` | `string` | The raw unparsed text of the MRZ. | +| `firstName` | `string` | The first name of the MRZ document holder. | +| `lastName` | `string` | The last name of the MRZ document holder. | +| `age` | `string` | The age of the MRZ document holder. | +| `sex` | `string` | The sex of the MRZ document holder. | +| `issuingState` | `string` | The issuing state (represented as the full name of the country/region) of the MRZ document. | +| `nationality` | `string` | The nationality (represented as the full name of the country/region) of the MRZ document holder. | +| `dateOfBirth` | `MRZDate` | The date of birth of the MRZ document holder. | +| `dateOfExpiry` | `MRZDate` | The date of expiry of the MRZ document. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.data.firstName); // prints the first name + console.log(result.data.lastName); // prints the last name + console.log(result.data.sex); // prints the sex + console.log(result.data.nationality); // prints the nationality + console.log(result.data.documentNumber); // prints the MRZ document number +})(); +``` + +### MRZDate + +MRZDate is used to represent the date fields of a `MRZData` object. + +#### Syntax + +```ts +interface MRZDate { + year: number; + month: number; + day: number; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `year` | `number` | The year of the date. | +| `month` | `number` | The month of the date. | +| `day` | `number` | The day of the date. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.data.dateOfBirth.year); // prints the year of the date of birth + console.log(result.data.dateOfBirth.month); // prints the month of the date of birth + console.log(result.data.dateOfBirth.day); // prints the day of the date of birth +})(); +``` + +### ResultStatus + +ResultStatus is used to represent the status of the MRZ Result. This status can be **successful**, **cancelled** if the user closes the scanner, or **failed** if something went wrong during the scanning process. The *code* of the result status is a [`EnumResultStatus`]({{ site.api }}enums-mrz-scanner.md#enumresultstatus). + +#### Syntax + +```ts +type ResultStatus = { + code: EnumResultStatus; + message?: string; +}; +``` + +#### Example + +Please see the [example of MRZResult](#example-8). diff --git a/api/mrz-scanner.md b/api/mrz-scanner.md index 0242798..48f1c4e 100644 --- a/api/mrz-scanner.md +++ b/api/mrz-scanner.md @@ -140,9 +140,9 @@ interface MRZScannerConfig { | `templateFilePath` | `string` | The file path to the custom JSON template used to customize the scanning process. | | `utilizedTemplateNames` | `UtilizedTemplateNames` | Specifies MRZ scanning templates. | | `engineResourcePaths` | `EngineResourcePaths` | Paths to the necessary resources for the MRZ scanning engine. | -| `scannerViewConfig` | `MRZScannerViewConfig` | Configuration settings for the MRZ scanner view. | -| `resultViewConfig` | `MRZResultViewConfig` | Configuration settings for the MRZ result view. | -| `mrzFormatType` | `EnumMRZDocumentType` | Specifies the MRTD formats that the application will support. | +| `scannerViewConfig` | [`MRZScannerViewConfig`](#mrzscannerviewconfig) | Configuration settings for the MRZ scanner view. | +| `resultViewConfig` | [`MRZResultViewConfig`](#mrzresultviewconfig) | Configuration settings for the MRZ result view. | +| `mrzFormatType` | [`EnumMRZDocumentType`]({{ site.api }}enums-mrz-scanner.html#enummrzdocumenttype) | Specifies the MRTD formats that the application will support. | | `showResultView` | `boolean` | Determines whether the final result view (MRZResultView) will be shown or not. | #### Example @@ -201,7 +201,7 @@ interface MRZScannerViewConfig { | Property | Type | Description | | ----------------------- | ------------------------------ | --------------------------------------------------------------- | -| `cameraEnhancerUIPath` | `string` | Path to the custom Camera Enhancer UI (`.html` template file) for the scanner view. | +| `uiPath` | `string` | Path to the custom Camera Enhancer UI (`.html` template file) for the scanner view. | | `container` | `HTMLElement \ string` | The container element or selector for the `MRZScannerView` UI. | | `showScanGuide` | `boolean` | Determines whether the scan guide frame will be displayed or not. | | `showUploadImage` | `boolean` | Determines the visibility of the "load image" icon to allow the user to select a static image from their local photo library. | @@ -254,8 +254,11 @@ interface MRZResultViewConfig { toolbarButtonsConfig?: MRZResultViewToolbarButtonsConfig; showOriginalImage?: boolean; allowResultEditing?: boolean; // New option to control if result fields can be edited + showMRZText?: boolean; + emptyResultMessage?: string; onDone?: (result: MRZResult) => Promise; + onCancel?: (result: MRZResult) => Promise; } ``` @@ -267,13 +270,19 @@ interface MRZResultViewConfig { | `toolbarButtonsConfig` | `MRZResultViewToolbarButtonsConfig` | Configures the main bottom toolbar of the result view. | | `showOriginalImage` | `boolean` | Determines whether the cropped image of the MRZ document will be displayed in the result view or not. | | `allowResultEditing` | `boolean` | Enables/disables the ability to edit the MRZ info after it is scanned. | +| `showMRZText` | `boolean` | Shows/hides the raw MRZ text as one of the fields in the result view. | +| `emptyResultMessage` | `string` | Sets the message to be displayed in the result view when no MRZ is detected. | | `onDone` | `Promise` | Defines the action(s) to take once the user clicks the "Done" button in the result view. | +| `onCancel` | `Promise` | Defines the action(s) to take once the user clicks the "Cancel" button in the result view when the MRZ scanner is launched with a static file. | #### Example ```ts const mrzResultViewConfig = { showOriginalImage: false, // Hides the cropped image of the MRZ document in the result view; true by default + allowResultEditing: true, // Allows the user to manually edit the text of the parsed result fields; false by default + showMRZText: false, // Hides the raw MRZ text as a field in the result view; true by default + emptyResultMessage: "No MRZ is detected. Please try again.", // Change the message if there is no MRZ is detected. The default message is "The necessary information couldn't be detected. Please try again." toolbarButtonsConfig: { retake: { label: "Re-scan", // Changes the text label of the retake button to "Re-scan"; string is "Re-take" by default @@ -282,12 +291,21 @@ const mrzResultViewConfig = { done: { label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default isHidden: false // Hides the done button; false by default + }, + cancel: { + label: "Try Again", // Changes the text label of the cancel button; string is "Cancel" by default + isHidden: false // Hides the cancel button; false by default. } }, /* onDone is a callback that allows you to define the action(s) to take once the user clicks the Done button and the scanner is closed. By default, nothing happens and the app goes back to the landing page. */ onDone: (result) => { console.log(result.status.message); console.log(result.data.firstName); + }, + /* onCancel is a callback that allows you to define the action(s) that will happen once the user clicks the Cancel button which only shows up if the MRZ scanner is launched with a static file rather than with the camera view. By default, nothing happens and the app goes back to the landing page */ + onCancel: (result) => { + console.log(result.status.message); + console.log(result.data.firstName); } }; @@ -307,6 +325,7 @@ The `MRZResultViewToolbarButtonsConfig` is used to configure the buttons of the interface MRZResultViewToolbarButtonsConfig { retake?: ToolbarButtonConfig; done?: ToolbarButtonConfig; + cancel?: ToolbarButtonConfig; } ``` @@ -314,8 +333,9 @@ interface MRZResultViewToolbarButtonsConfig { | Property | Type | Description | | ----------------------- | ------------------------------ | --------------------------------------------------------------- | -| `retake` | `ToolbarButtonConfig` | Configuration for the re-scan button of the toolbar. | -| `done` | `ToolbarButtonConfig` | Configuration for the done button of the toolbar. | +| `retake` | [`ToolbarButtonConfig`](#toolbarbuttonconfig) | Configuration for the re-scan button of the toolbar. | +| `done` | [`ToolbarButtonConfig`](#toolbarbuttonconfig) | Configuration for the done button of the toolbar. | +| `cancel` | [`ToolbarButtonConfig`](#toolbarbuttonconfig) | Configuration for the cancel button of the toolbar (which only shows up if the MRZ Scanner is launched with a static file instead of the standard camera UI). | #### Example @@ -328,6 +348,10 @@ const mrzButtonConfig = { done: { label: "Return Home", isHidden: false + }, + cancel: { + label: "Try Again", + isHidden: false } }; @@ -438,8 +462,8 @@ export interface MRZData { | `issuingStateRaw` | `string` | The raw text from the MRZ string of the issuing state of the MRZ document. | | `nationality` | `string` | The nationality (represented as the full name of the country/region) of the MRZ document holder. | | `nationalityRaw` | `string` | The raw text from the MRZ string representing the nationality of the document holder. | -| `dateOfBirth` | `MRZDate` | The date of birth of the MRZ document holder. | -| `dateOfExpiry` | `MRZDate` | The date of expiry of the MRZ document. | +| `dateOfBirth` | [`MRZDate`](#mrzdate) | The date of birth of the MRZ document holder. | +| `dateOfExpiry` | [`MRZDate`](#mrzdate) | The date of expiry of the MRZ document. | #### Example diff --git a/codegallery/helloworld/index.md b/codegallery/helloworld/index.md index 94d4ef3..c41b2b8 100644 --- a/codegallery/helloworld/index.md +++ b/codegallery/helloworld/index.md @@ -23,7 +23,7 @@ Hello World represents the most basic implementation of the MRZ Scanner. One of Dynamsoft MRZ Scanner - Hello World - + diff --git a/guides/mrz-scanner-customization.md b/guides/mrz-scanner-customization.md index 5359a61..8a3f72e 100644 --- a/guides/mrz-scanner-customization.md +++ b/guides/mrz-scanner-customization.md @@ -169,12 +169,14 @@ The **`MRZResultView`** user interface displays the parsed MRZ results as well a 1. **`container`** - assign a specific DOM element to contain the `**MRZResultView**` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. -2. **`toolbarButtonsConfig`** - configure the `MRZResultView` toolbar located in the footer in portrait mode, and on the right hand side of the screen in landscape. The **re-take button** takes the user back to the `MRZScannerView` to scan a new MRZ, discarding the previously scanned result. The other button is a **done button** that closes the scanner and destroys the `MRZScanner` instance. We explain how to use the `toolbarButtonsConfig` to customize this tool bar. +2. **`toolbarButtonsConfig`** - configure the `MRZResultView` toolbar located in the footer in portrait mode, and on the right hand side of the screen in landscape. The **re-take button** takes the user back to the `MRZScannerView` to scan a new MRZ, discarding the previously scanned result. The other button is a **done button** that closes the scanner and destroys the `MRZScanner` instance. We explain how to use the `toolbarButtonsConfig` to customize this tool bar. The **cancel button** appears in place of the re-take button when the MRZ Scanner is launched with a static file instead of the standard camera UI. 3. **`showOriginalImage`** (default value `true`) - show or hide the cropped image of the scanned MRZ document at the top of the View. Set this property to `false` to hide the image. 4. **`allowResultEditing`** (default value `false`) - control whether or not the parsed text fields can be edited by the user. In certain cases, the MRZ text result parsed by the SDK may not exactly match the text present on the MRZ document. You may choose to allow the user to edit the result fields after cross-checking them with the info present on the document itself by displaying the original document with `showOriginalImage: true`. +5. + 5. **`onDone`** - set a callback function to be executed upon exiting the MRZ Scanner workflow when the user clicks the *Done* button. This callback receives the MRZResult object representing the full MRZ result (including the scanned image and the parsed MRZ string) for further processing after closing the MRZ Scanner and entering the next stage of your application's workflow. Read more about implementing `onDone` in the [following section](#configuring-the-ondone-callback). ### Using the `MRZResultViewConfig` diff --git a/guides/mrz-scanner-static-image.md b/guides/mrz-scanner-static-image.md index 9e0e84e..f27b8c3 100644 --- a/guides/mrz-scanner-static-image.md +++ b/guides/mrz-scanner-static-image.md @@ -13,7 +13,7 @@ permalink: /guides/mrz-scanner-static-image.html In the main [MRZ Scanner JS User Guide]({{ site.guides }}mrz-scanner.html), we explored how to use the default UI of the MRZ Scanner to read MRZs via interactive video stream while at the same time including the ability to read from photos in your photo library via the Load Image button that is part of the [`MRZScannerView`]({{ site.guides }}mrz-scanner.html#mrzscannerview). -With the arrival of **v2.1** of the MRZ Scanner, the library has introduced the ability to read MRZs directly from static images without the need to use the file/photo picker that is a default part of the mobile device or the computer. In this guide, we will explore how to use the MRZ Scanner API in order to read MRZs from multiple image formats, as well as PDFs. +In **v2.1** (and beyond) of the MRZ Scanner, the library has introduced the ability to read MRZs directly from static images without the need to use the file/photo picker that is a default part of the mobile device or the computer. In this guide, we will explore how to use the MRZ Scanner API in order to read MRZs from multiple image formats, as well as PDFs. > [!NOTE] > In order to follow with this guide, please refer to the [**use-file-input sample**](https://github.com/Dynamsoft/mrz-scanner-javascript/tree/main/samples/scenarios/use-file-input.html) that is hosted on the main Github repo of the MRZ Scanner source files. diff --git a/guides/mrz-scanner-v2.0.md b/guides/mrz-scanner-v2.0.md new file mode 100644 index 0000000..e4bd9ec --- /dev/null +++ b/guides/mrz-scanner-v2.0.md @@ -0,0 +1,265 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition +keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, +description: Dynamsoft MRZ Scanner User Guide +permalink: /guides/mrz-scanner.html +--- + +# User Guide for the MRZ Scanner JavaScript Edition + +This user guide will walk you through a Hello World sample web application that scans MRZ documents using the MRZ Scanner JavaScript Edition SDK. We recommend using this sample as a reference when creating your own application. + +> [!TIP] +> Please visit the [Introduction]({{ site.introduction }}index.html) page to learn about the MRZ document formats, the architecture of the MRZ Scanner with respect to other Dynamsoft products, and the system requirements of the MRZ Scanner JavaScript Edition. + +## License + +### Trial License + +When getting started with MRZ Scanner, we recommend getting your own 30-day trial license through the following modal: + +{% include trialLicense.html %} + +The trial license can be renewed via the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense/?product=mrz&utm_source=guide&package=js) twice, each time for another 15 days, giving you a total of 60 days to develop your own application using the solution. Please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) if you need more time for a full evaluation or have any questions. + +> [!NOTE] +> The **MRZ Scanner** license contains a license for the **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and the **Dynamsoft Camera Enhancer** since the MRZ Scanner builds on top of those three products. + +### Full License + +If you are fully satisfied with the solution and would like to move forward with a full license, please contact the [Dynamsoft Sales Team](https://www.dynamsoft.com/company/contact/). + +## Quick Start - Hello World + +As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the [samples Github repo](https://github.com/Dynamsoft/mrz-scanner-javascript). + +The first step before writing the code is to include the SDK in your application. You can simply include the SDK by using the precompiled script, but you can also build the SDK from source yourself. + +
+ +
+
Use the Precompiled Script
+ +The simplest way to include the SDK is to use either the [**jsDelivr**](https://jsdelivr.com/) or [**UNPKG**](https://unpkg.com/) CDN. The Hello World sample that this guide will explore uses **jsDelivr**: + +- jsDelivr + + ```html + + ``` + +- UNPKG + + ```html + + ``` + +When using a framework such as **React**, **Vue** or **Angular**, we recommend adding the package as a dependency using a package manager such as **npm** or **yarn**: + + ```sh + npm i dynamsoft-mrz-scanner@2.0.0 -E + # or + yarn add dynamsoft-mrz-scanner@2.0.0 -E + ``` + +> [!WARNING] +> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. + +Below is the complete Hello World sample page that uses the precompiled script served via a CDN. + +```html + + + + + + Dynamsoft MRZ Scanner - Hello World + + + + +

Dynamsoft MRZ Scanner

+ + + + +``` + +> [!NOTE] +> +> This code is a more simplified version of the Hello World file that is hosted on [Github](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/samples/hello-world.html). +> The file hosted on Github contains more code for a better final UI, but that extra code is not necessary to successfully launching the MRZ Scanner. All you need is the code shown above. +> Please do not forget to replace `YOUR_LICENSE_KEY_HERE` with your own license key, whether it is trial or full. + +To run the sample, create a new file called `hello-world.html`, then copy and paste the code above into the file. Next, serve the page directly by deploying it to a server. + +If you are using VS Code, a quick and easy way to serve the project is using the [Five Server VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). Simply install the extension, open the `hello-world.html` file in the editor, and click "Go Live" in the bottom right corner of the editor. This will serve the application at `http://127.0.0.1:5500/hello-world.html`. + +Alternatively, you can use other methods like `IIS` or `Apache` to serve the project, though we will omit those methods here for brevity. + +
+ +
+
Build from Source
+ +While using the pre-compiled script is the easiest way to get started with the MRZ Scanner, we do also allow you to build the MRZ Scanner SDK from source. Building from source gives you the advantage of performing in-depth SDK customization. The MRZ Scanner is built using three constituent Dynamsoft products: **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and **Dynamsoft Camera Enhancer**, so any MRZ Scanner customization involves working with these products. + +Building the SDK from source involves retrieving the **MRZ Scanner JavaScript Edition** source files from the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo. + +Follow these steps in order to build from the source: + +1. Download the **MRZ Scanner JavaScript Edition** source files from [Github](https://github.com/Dynamsoft/mrz-scanner-javascript) as a compressed folder ("Download ZIP" option). + +2. Extract the contents of the compressed folder. + +3. Open the *Hello World* sample included with the source files located at `/samples/hello-world.html` (relative path to the decompressed directory) using your code editor of choice (like VS Code). + +4. Search for 'YOUR_LICENSE_KEY_HERE' and replace that with your own license key, whether it is trial or full. + +5. Install project dependencies - in the terminal, navigate to the project root directory and run the following: + ```bash + npm install + ``` + +6. Build the project - once the dependencies are installed, build the project by running: + ```bash + npm run build + ``` + +7. Serve the project via `localhost`: + ```bash + npm run serve + ``` +Once the server is running, open the application in a browser using the address provided in the terminal output from running `npm run serve`. + +
+ +
+ +## Breaking down Hello World + +Let's now go through the code of the Hello World sample to understand how the code works in detail. + +### Step 1: Setting up the HTML and Including the MRZ Scanner + +```html + + + + + + Dynamsoft MRZ Scanner - Hello World + + + + +

Dynamsoft MRZ Scanner

+ + + +``` + +The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---hello-world) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: + +MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it creates a container which it populates with the **Ready-to-Use UI**. + +### Step 2: Initializing the MRZ Scanner + +```html + +

Dynamsoft MRZ Scanner

+ + + +``` + +Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. + +### Step 3: Launching the MRZ Scanner + +```html + +``` + +Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: + +#### `MRZScannerView` + +The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), which is composed of the following UI elements: + +1. **Camera View**: The Camera View is the camera viewfinder UI component within the `MRZScannerView`. This viewfinder occupies the majority of the space within the MRZScannerView to give the user a clear view and precise control of the image being scanned. + +2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame. + +
+ Scan Guide Frames +

+ +3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page. + +
+ Scan Guide Frames +

+ +4. **Resolution/Camera Select Dropdown**: This dropdown allows the user to switch cameras (should they have more than one available on the device), or select a different resolution for the camera that is currently selected. + +5. **Load Image Button**: This button allows the user to scan a file of an image that contains a MRZ from the device's local storage. + +6. **Sound Button**: When toggled on, the MRZ Scanner plays a *beep* sound to signal when the scanner recognizes an MRZ. + +7. **Flash Button**: This button is responsible for toggling the flash of the camera (when one is available). The flash button does not appear if the device does not have a camera flash, or the browser does not support camera flash. + +8. **Close Scanner Button**: This button closes the MRZ Scanner and takes the user back to the landing page. + +> [!NOTE] +> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. + +#### `MRZResultView` + +Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig): + +1. **Original Image**: A cropped image of the scanned MRZ document - this gets displayed at the top of the `MRZResultView` by default. + +2. **Parsed Results**: The data parsed from the MRZ code, displayed with their corresponding field names (e.g. Given Name, Nationality, etc.) are placed below the cropped image of the MRZ corresponding field names. In addition to displaying these parsed results, the MRZ Scanner allows the user to edit the values of the fields in case of any errors by cross referencing from the cropped MRZ document displayed directly above. + +3. **Re-take Button**: This button discards the previous scan and parsed data, then takes the user back to the **`MRZScannerView`** to scan another MRZ document. + +4. **Done Button**: This button closes the scanner and destroys the **`MRZScanner`** instance, and returns the result object containing the MRZ scan. At that point, the application goes back to the landing page. You can additionally dictate further actions upon the button click, such as allowing the user to perform some extra actions with the MRZ result, navigating to another page, passing the result object for further processing, and more. + + > [!NOTE] + > In the Hello World sample, no action is taken once the Done button is clicked. The scanner closes and the user is met with an empty page. In order to open the scanner again, the user must refresh the page. You may choose to implement a more user-friendly behavior in a production environment, such as presenting the user with an option to re-open the MRZ Scanner upon closing it. + +## Next Steps + +Now that you got the most basic functionality of the MRZ Scanner up and running, it's time to explore the many ways in which the MRZ Scanner can be used, including customization and the ability to read directly from static images and PDFs. To learn more about those two topics, please visit the following articles + +- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html) +- [Setting up the MRZ Scanner for Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) \ No newline at end of file diff --git a/guides/mrz-scanner-v2.1.md b/guides/mrz-scanner-v2.1.md new file mode 100644 index 0000000..637a5ac --- /dev/null +++ b/guides/mrz-scanner-v2.1.md @@ -0,0 +1,265 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition +keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, +description: Dynamsoft MRZ Scanner User Guide +permalink: /guides/mrz-scanner.html +--- + +# User Guide for the MRZ Scanner JavaScript Edition + +This user guide will walk you through a Hello World sample web application that scans MRZ documents using the MRZ Scanner JavaScript Edition SDK. We recommend using this sample as a reference when creating your own application. + +> [!TIP] +> Please visit the [Introduction]({{ site.introduction }}index.html) page to learn about the MRZ document formats, the architecture of the MRZ Scanner with respect to other Dynamsoft products, and the system requirements of the MRZ Scanner JavaScript Edition. + +## License + +### Trial License + +When getting started with MRZ Scanner, we recommend getting your own 30-day trial license through the following modal: + +{% include trialLicense.html %} + +The trial license can be renewed via the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense/?product=mrz&utm_source=guide&package=js) twice, each time for another 15 days, giving you a total of 60 days to develop your own application using the solution. Please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) if you need more time for a full evaluation or have any questions. + +> [!NOTE] +> The **MRZ Scanner** license contains a license for the **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and the **Dynamsoft Camera Enhancer** since the MRZ Scanner builds on top of those three products. + +### Full License + +If you are fully satisfied with the solution and would like to move forward with a full license, please contact the [Dynamsoft Sales Team](https://www.dynamsoft.com/company/contact/). + +## Quick Start - Hello World + +As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the [samples Github repo](https://github.com/Dynamsoft/mrz-scanner-javascript). + +The first step before writing the code is to include the SDK in your application. You can simply include the SDK by using the precompiled script, but you can also build the SDK from source yourself. + +
+ +
+
Use the Precompiled Script
+ +The simplest way to include the SDK is to use either the [**jsDelivr**](https://jsdelivr.com/) or [**UNPKG**](https://unpkg.com/) CDN. The Hello World sample that this guide will explore uses **jsDelivr**: + +- jsDelivr + + ```html + + ``` + +- UNPKG + + ```html + + ``` + +When using a framework such as **React**, **Vue** or **Angular**, we recommend adding the package as a dependency using a package manager such as **npm** or **yarn**: + + ```sh + npm i dynamsoft-mrz-scanner@3.0.0 -E + # or + yarn add dynamsoft-mrz-scanner@3.0.0 -E + ``` + +> [!WARNING] +> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. + +Below is the complete Hello World sample page that uses the precompiled script served via a CDN. + +```html + + + + + + Dynamsoft MRZ Scanner - Hello World + + + + +

Dynamsoft MRZ Scanner

+ + + + +``` + +> [!NOTE] +> +> This code is a more simplified version of the Hello World file that is hosted on [Github](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/samples/hello-world.html). +> The file hosted on Github contains more code for a better final UI, but that extra code is not necessary to successfully launching the MRZ Scanner. All you need is the code shown above. +> Please do not forget to replace `YOUR_LICENSE_KEY_HERE` with your own license key, whether it is trial or full. + +To run the sample, create a new file called `hello-world.html`, then copy and paste the code above into the file. Next, serve the page directly by deploying it to a server. + +If you are using VS Code, a quick and easy way to serve the project is using the [Five Server VSCode extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server). Simply install the extension, open the `hello-world.html` file in the editor, and click "Go Live" in the bottom right corner of the editor. This will serve the application at `http://127.0.0.1:5500/hello-world.html`. + +Alternatively, you can use other methods like `IIS` or `Apache` to serve the project, though we will omit those methods here for brevity. + +
+ +
+
Build from Source
+ +While using the pre-compiled script is the easiest way to get started with the MRZ Scanner, we do also allow you to build the MRZ Scanner SDK from source. Building from source gives you the advantage of performing in-depth SDK customization. The MRZ Scanner is built using three constituent Dynamsoft products: **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and **Dynamsoft Camera Enhancer**, so any MRZ Scanner customization involves working with these products. + +Building the SDK from source involves retrieving the **MRZ Scanner JavaScript Edition** source files from the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo. + +Follow these steps in order to build from the source: + +1. Download the **MRZ Scanner JavaScript Edition** source files from [Github](https://github.com/Dynamsoft/mrz-scanner-javascript) as a compressed folder ("Download ZIP" option). + +2. Extract the contents of the compressed folder. + +3. Open the *Hello World* sample included with the source files located at `/samples/hello-world.html` (relative path to the decompressed directory) using your code editor of choice (like VS Code). + +4. Search for 'YOUR_LICENSE_KEY_HERE' and replace that with your own license key, whether it is trial or full. + +5. Install project dependencies - in the terminal, navigate to the project root directory and run the following: + ```bash + npm install + ``` + +6. Build the project - once the dependencies are installed, build the project by running: + ```bash + npm run build + ``` + +7. Serve the project via `localhost`: + ```bash + npm run serve + ``` +Once the server is running, open the application in a browser using the address provided in the terminal output from running `npm run serve`. + +
+ +
+ +## Breaking down Hello World + +Let's now go through the code of the Hello World sample to understand how the code works in detail. + +### Step 1: Setting up the HTML and Including the MRZ Scanner + +```html + + + + + + Dynamsoft MRZ Scanner - Hello World + + + + +

Dynamsoft MRZ Scanner

+ + + +``` + +The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---hello-world) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: + +MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it creates a container which it populates with the **Ready-to-Use UI**. + +### Step 2: Initializing the MRZ Scanner + +```html + +

Dynamsoft MRZ Scanner

+ + + +``` + +Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. + +### Step 3: Launching the MRZ Scanner + +```html + +``` + +Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: + +#### `MRZScannerView` + +The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), which is composed of the following UI elements: + +1. **Camera View**: The Camera View is the camera viewfinder UI component within the `MRZScannerView`. This viewfinder occupies the majority of the space within the MRZScannerView to give the user a clear view and precise control of the image being scanned. + +2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame. + +
+ Scan Guide Frames +

+ +3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page. + +
+ Scan Guide Frames +

+ +4. **Resolution/Camera Select Dropdown**: This dropdown allows the user to switch cameras (should they have more than one available on the device), or select a different resolution for the camera that is currently selected. + +5. **Load Image Button**: This button allows the user to scan a file of an image that contains a MRZ from the device's local storage. + +6. **Sound Button**: When toggled on, the MRZ Scanner plays a *beep* sound to signal when the scanner recognizes an MRZ. + +7. **Flash Button**: This button is responsible for toggling the flash of the camera (when one is available). The flash button does not appear if the device does not have a camera flash, or the browser does not support camera flash. + +8. **Close Scanner Button**: This button closes the MRZ Scanner and takes the user back to the landing page. + +> [!NOTE] +> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. + +#### `MRZResultView` + +Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig): + +1. **Original Image**: A cropped image of the scanned MRZ document - this gets displayed at the top of the `MRZResultView` by default. + +2. **Parsed Results**: The data parsed from the MRZ code, displayed with their corresponding field names (e.g. Given Name, Nationality, etc.) are placed below the cropped image of the MRZ corresponding field names. In addition to displaying these parsed results, the MRZ Scanner allows the user to edit the values of the fields in case of any errors by cross referencing from the cropped MRZ document displayed directly above. + +3. **Re-take Button**: This button discards the previous scan and parsed data, then takes the user back to the **`MRZScannerView`** to scan another MRZ document. + +4. **Done Button**: This button closes the scanner and destroys the **`MRZScanner`** instance, and returns the result object containing the MRZ scan. At that point, the application goes back to the landing page. You can additionally dictate further actions upon the button click, such as allowing the user to perform some extra actions with the MRZ result, navigating to another page, passing the result object for further processing, and more. + + > [!NOTE] + > In the Hello World sample, no action is taken once the Done button is clicked. The scanner closes and the user is met with an empty page. In order to open the scanner again, the user must refresh the page. You may choose to implement a more user-friendly behavior in a production environment, such as presenting the user with an option to re-open the MRZ Scanner upon closing it. + +## Next Steps + +Now that you got the most basic functionality of the MRZ Scanner up and running, it's time to explore the many ways in which the MRZ Scanner can be used, including customization and the ability to read directly from static images and PDFs. To learn more about those two topics, please visit the following articles + +- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html) +- [Setting up the MRZ Scanner for Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) \ No newline at end of file diff --git a/guides/mrz-scanner.md b/guides/mrz-scanner.md index bb479e3..7633f40 100644 --- a/guides/mrz-scanner.md +++ b/guides/mrz-scanner.md @@ -33,7 +33,7 @@ The trial license can be renewed via the [customer portal](https://www.dynamsoft If you are fully satisfied with the solution and would like to move forward with a full license, please contact the [Dynamsoft Sales Team](https://www.dynamsoft.com/company/contact/). -## Quick Start - Hello World +## Quick Start - Including the Library As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the [samples Github repo](https://github.com/Dynamsoft/mrz-scanner-javascript). @@ -49,21 +49,21 @@ The simplest way to include the SDK is to use either the [**jsDelivr**](https:// - jsDelivr ```html - + ``` - UNPKG ```html - + ``` When using a framework such as **React**, **Vue** or **Angular**, we recommend adding the package as a dependency using a package manager such as **npm** or **yarn**: ```sh - npm i dynamsoft-mrz-scanner@2.1.0 -E + npm i dynamsoft-mrz-scanner@3.0.0 -E # or - yarn add dynamsoft-mrz-scanner@2.1.0 -E + yarn add dynamsoft-mrz-scanner@3.0.0 -E ``` > [!WARNING] @@ -78,7 +78,7 @@ Below is the complete Hello World sample page that uses the precompiled script s Dynamsoft MRZ Scanner - Hello World - + @@ -115,9 +115,11 @@ Alternatively, you can use other methods like `IIS` or `Apache` to serve the pro
Build from Source
-While using the pre-compiled script is the easiest way to get started with the MRZ Scanner, we do also allow you to build the MRZ Scanner SDK from source. Building from source gives you the advantage of performing in-depth SDK customization. The MRZ Scanner is built using three constituent Dynamsoft products: **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and **Dynamsoft Camera Enhancer**, so any MRZ Scanner customization involves working with these products. +While using the pre-compiled script is the easiest way to get started with the MRZ Scanner, we do also allow you to build the MRZ Scanner SDK from source. Building from source gives you the advantage of performing in-depth SDK customization. -Building the SDK from source involves retrieving the **MRZ Scanner JavaScript Edition** source files from the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiles them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo. +The MRZ Scanner is built using three constituent Dynamsoft products: [**Dynamsoft Label Recognizer**]({{ site.dlr_js }}), [**Dynamsoft Code Parser**]({{ site.dcp_js }}api-reference/code-parser-module.html?lang=javascript), and [**Dynamsoft Camera Enhancer**]({{ site.dce_js }}api-reference/index.html?lang=javascript), so any MRZ Scanner customization involves working with the foundational API of these products. + +The first step to building the SDK from source is retrieving the **MRZ Scanner JavaScript Edition** source files from the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiling them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo. Follow these steps in order to build from the source: @@ -147,6 +149,42 @@ Once the server is running, open the application in a browser using the address
+
+
Self-hosting the Library Resources
+ +There could be situations where you don't want to connect to the CDN repository in order to include the library in your application. We also provide the option to download the library's resource files, and then placing them into your own server so that the users of your application would only need to connect to your server. + +The first step is to get a copy of the resources. There are two ways which you can do this: + +- Go to the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript). Download the repository as a ZIP and the library resources are in the *dist* folder. So all you need is just a copy of this *dist* folder. + +- If you are using `npm`, you could also install the package and extract the `dist` folder from the package in `node_modules`. Install the package using the command `npm i dynamsoft-mrz-scanner@3.0.0 -E`. Find the `dynamsoft-mrz-scanner` fodler in `node_modules` and the *dist* folder will be inside. + +Once you have the dist folder, the next step is to deploy it to a server of your choice. There are a couple of considerations to take into account when setting up the server: + +- Secure context (HTTPS deployment) + + When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons + + - Access to the camera video stream is only granted in a security context. Most browsers impose this restriction. + > Some browsers like Chrome may grant the access for `http://127.0.0.1` and `http://localhost` or even for pages opened directly from the local disk (`file:///...`). This can be helpful for temporary development and test. + + - Dynamsoft License requires a secure context to work. + +- Set the MIME type for `.wasm` as `application/wasm` + + The goal is to configure your server to send the correct Content-Type header for the wasm file so that it is processed correctly by the browser. + + Different types of webservers are configured differently, for example: + + + Apache + + IIS + + NGINX + +Once you are done with the server setup and the library resources are placed in their desired location on the server - the final thing is to tell the library where to find the resources at runtime. This is done by configuring the *engineResourcePaths* of the `MRZScannerConfig` object. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. The *engineResourcePaths* needs to be set to the location of the library resources on the server that you just set up. + +
+
## Breaking down Hello World @@ -162,7 +200,7 @@ Let's now go through the code of the Hello World sample to understand how the co Dynamsoft MRZ Scanner - Hello World - + diff --git a/releasenotes/index.md b/releasenotes/index.md index 3d30ccb..5b8c1c6 100644 --- a/releasenotes/index.md +++ b/releasenotes/index.md @@ -12,6 +12,21 @@ permalink: /releasenotes/index.html # Release Notes +## 3.0.0 (06/17/2025) + +## Highlighted Features + +- Updated the underlying Capture Vision bundle to `3.0.3001` for major improvements in reading accuracy and speed. +- Optimized the algorithm to achieve a **30% increase in read rate** as well as +- Added support for `TD2` and `TD3` Visa. +- Added a `emptyResultMessage` property to the `ResultViewConfig` interface in order to change the string message that is displayed when no result is found. + +## Fixes + +- Fixed the issue where the camera select icon cuts off on browsers in iOS. +- Optimized the resource loading process of the library. +- Replaced the re-scan button of the result view with a cancel button when the MRZ scanner is launched with a static file. + ## 2.1.0 (05/16/2025) ## Highlighted Features From 963b2881c1d4a2afcbe38eef6cd9d47817dcc2a4 Mon Sep 17 00:00:00 2001 From: Amro-Dynamsoft Date: Thu, 19 Jun 2025 16:30:05 -0700 Subject: [PATCH 3/3] Staging (#17) * update to internal commit 20965a62 * chore: fix .gitignore * feat: GitHub preview CI workflow * chore: fix whitespace, EOF newline, and styling * fix: formatting * v3 deployment All the docs have been updated to v3. What is left will be to fix the versioning for 2.0 and 2.1 * Fixes and versioning Mainly needed to address the mistakes as well as add versioning for 2.1 and 2.0 --------- Co-authored-by: DMGithubPublisher <65145280+DMGithubPublisher@users.noreply.github.com> Co-authored-by: Justin-Dynamsoft <33125453+a362758199@users.noreply.github.com> Co-authored-by: Tom Kent Co-authored-by: Amro Anwer Co-authored-by: DMGithubPublisher Co-authored-by: dynamsoft-h <172081603+dynamsoft-h@users.noreply.github.com> --- _includes/sidelist-api-v2.0.html | 8 + _includes/sidelist-api-v2.1.html | 8 + _includes/sidelist-codegallery-v2.0.html | 11 + _includes/sidelist-codegallery-v2.1.html | 11 + _includes/sidelist-full-tree-v2.0.html | 6 + _includes/sidelist-full-tree-v2.1.html | 6 + _includes/sidelist-guides-v2.0.html | 6 + _includes/sidelist-guides-v2.1.html | 7 + _includes/sidelist-introduction-v2.0.html | 1 + _includes/sidelist-introduction-v2.1.html | 1 + _includes/sidelist-releasenotes-v2.0.html | 1 + _includes/sidelist-releasenotes-v2.1.html | 1 + api/mrz-scanner-v2.0.md | 6 +- api/mrz-scanner-v2.1.md | 513 ++++++++++++++++++++++ api/mrz-scanner.md | 7 +- guides/mrz-scanner-customization-v2.0.md | 234 ++++++++++ guides/mrz-scanner-customization-v2.1.md | 260 +++++++++++ guides/mrz-scanner-customization.md | 13 +- guides/mrz-scanner-v2.0.md | 27 +- guides/mrz-scanner-v2.1.md | 32 +- guides/mrz-scanner.md | 8 +- releasenotes/index.md | 2 +- 22 files changed, 1125 insertions(+), 44 deletions(-) create mode 100644 _includes/sidelist-api-v2.0.html create mode 100644 _includes/sidelist-api-v2.1.html create mode 100644 _includes/sidelist-codegallery-v2.0.html create mode 100644 _includes/sidelist-codegallery-v2.1.html create mode 100644 _includes/sidelist-full-tree-v2.0.html create mode 100644 _includes/sidelist-full-tree-v2.1.html create mode 100644 _includes/sidelist-guides-v2.0.html create mode 100644 _includes/sidelist-guides-v2.1.html create mode 100644 _includes/sidelist-introduction-v2.0.html create mode 100644 _includes/sidelist-introduction-v2.1.html create mode 100644 _includes/sidelist-releasenotes-v2.0.html create mode 100644 _includes/sidelist-releasenotes-v2.1.html create mode 100644 api/mrz-scanner-v2.1.md create mode 100644 guides/mrz-scanner-customization-v2.0.md create mode 100644 guides/mrz-scanner-customization-v2.1.md diff --git a/_includes/sidelist-api-v2.0.html b/_includes/sidelist-api-v2.0.html new file mode 100644 index 0000000..0280af3 --- /dev/null +++ b/_includes/sidelist-api-v2.0.html @@ -0,0 +1,8 @@ +
  • API Reference + + +
    • \ No newline at end of file diff --git a/_includes/sidelist-api-v2.1.html b/_includes/sidelist-api-v2.1.html new file mode 100644 index 0000000..32160bb --- /dev/null +++ b/_includes/sidelist-api-v2.1.html @@ -0,0 +1,8 @@ +
  • API Reference + + +
    • \ No newline at end of file diff --git a/_includes/sidelist-codegallery-v2.0.html b/_includes/sidelist-codegallery-v2.0.html new file mode 100644 index 0000000..37c1bdc --- /dev/null +++ b/_includes/sidelist-codegallery-v2.0.html @@ -0,0 +1,11 @@ +
  • Code Gallery + + + +
    • \ No newline at end of file diff --git a/_includes/sidelist-codegallery-v2.1.html b/_includes/sidelist-codegallery-v2.1.html new file mode 100644 index 0000000..37c1bdc --- /dev/null +++ b/_includes/sidelist-codegallery-v2.1.html @@ -0,0 +1,11 @@ +
  • Code Gallery + + + +
    • \ No newline at end of file diff --git a/_includes/sidelist-full-tree-v2.0.html b/_includes/sidelist-full-tree-v2.0.html new file mode 100644 index 0000000..7ce0eea --- /dev/null +++ b/_includes/sidelist-full-tree-v2.0.html @@ -0,0 +1,6 @@ +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-introduction-v2.0.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-guides-v2.0.html" -%} + +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-codegallery-v2.0.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-api-v2.0.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-releasenotes-v2.0.html" -%} \ No newline at end of file diff --git a/_includes/sidelist-full-tree-v2.1.html b/_includes/sidelist-full-tree-v2.1.html new file mode 100644 index 0000000..0557a16 --- /dev/null +++ b/_includes/sidelist-full-tree-v2.1.html @@ -0,0 +1,6 @@ +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-introduction-v2.1.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-guides-v2.1.html" -%} + +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-codegallery-v2.1.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-api-v2.1.html" -%} +{%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-releasenotes-v2.1.html" -%} \ No newline at end of file diff --git a/_includes/sidelist-guides-v2.0.html b/_includes/sidelist-guides-v2.0.html new file mode 100644 index 0000000..19e715d --- /dev/null +++ b/_includes/sidelist-guides-v2.0.html @@ -0,0 +1,6 @@ +
  • Developer Guides + +
    • \ No newline at end of file diff --git a/_includes/sidelist-guides-v2.1.html b/_includes/sidelist-guides-v2.1.html new file mode 100644 index 0000000..a77c063 --- /dev/null +++ b/_includes/sidelist-guides-v2.1.html @@ -0,0 +1,7 @@ +
  • Developer Guides + +
    • \ No newline at end of file diff --git a/_includes/sidelist-introduction-v2.0.html b/_includes/sidelist-introduction-v2.0.html new file mode 100644 index 0000000..9ec7e76 --- /dev/null +++ b/_includes/sidelist-introduction-v2.0.html @@ -0,0 +1 @@ +
  • Introduction
    • \ No newline at end of file diff --git a/_includes/sidelist-introduction-v2.1.html b/_includes/sidelist-introduction-v2.1.html new file mode 100644 index 0000000..9ec7e76 --- /dev/null +++ b/_includes/sidelist-introduction-v2.1.html @@ -0,0 +1 @@ +
  • Introduction
    • \ No newline at end of file diff --git a/_includes/sidelist-releasenotes-v2.0.html b/_includes/sidelist-releasenotes-v2.0.html new file mode 100644 index 0000000..c731573 --- /dev/null +++ b/_includes/sidelist-releasenotes-v2.0.html @@ -0,0 +1 @@ +
  • Release Notes
    • \ No newline at end of file diff --git a/_includes/sidelist-releasenotes-v2.1.html b/_includes/sidelist-releasenotes-v2.1.html new file mode 100644 index 0000000..c731573 --- /dev/null +++ b/_includes/sidelist-releasenotes-v2.1.html @@ -0,0 +1 @@ +
  • Release Notes
    • \ No newline at end of file diff --git a/api/mrz-scanner-v2.0.md b/api/mrz-scanner-v2.0.md index 6450b14..d361d09 100644 --- a/api/mrz-scanner-v2.0.md +++ b/api/mrz-scanner-v2.0.md @@ -235,6 +235,7 @@ interface MRZResultViewConfig { | `container` | `HTMLElement \ string` | The container element or selector for the `MRZResultView` UI. | | `toolbarButtonsConfig` | `MRZResultViewToolbarButtonsConfig` | Configures the main bottom toolbar of the result view. | | `showOriginalImage` | `boolean` | Determines whether the cropped image of the MRZ document will be displayed in the result view or not. | +| `showMRZText` | `boolean` | Displays/hides the raw MRZ text as one of the result fields in the result view. | | `allowResultEditing` | `boolean` | Enables/disables the ability to edit the MRZ info after it is scanned. | | `onDone` | `Promise` | Defines the action(s) to take once the user clicks the "Done" button in the result view. | @@ -243,6 +244,7 @@ interface MRZResultViewConfig { ```ts const mrzResultViewConfig = { showOriginalImage: false, // Hides the cropped image of the MRZ document in the result view; true by default + showMRZText: false, // Hides the raw MRZ text as a result field. toolbarButtonsConfig: { retake: { label: "Re-scan", // Changes the text label of the retake button to "Re-scan"; string is "Re-take" by default @@ -403,8 +405,8 @@ export interface MRZData { | `lastName` | `string` | The last name of the MRZ document holder. | | `age` | `string` | The age of the MRZ document holder. | | `sex` | `string` | The sex of the MRZ document holder. | -| `issuingState` | `string` | The issuing state (represented as the full name of the country/region) of the MRZ document. | -| `nationality` | `string` | The nationality (represented as the full name of the country/region) of the MRZ document holder. | +| `issuingState` | `string` | The issuing state of the MRZ document. | +| `nationality` | `string` | The nationality of the MRZ document holder. | | `dateOfBirth` | `MRZDate` | The date of birth of the MRZ document holder. | | `dateOfExpiry` | `MRZDate` | The date of expiry of the MRZ document. | diff --git a/api/mrz-scanner-v2.1.md b/api/mrz-scanner-v2.1.md new file mode 100644 index 0000000..91d95b6 --- /dev/null +++ b/api/mrz-scanner-v2.1.md @@ -0,0 +1,513 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition - API Reference +keywords: Documentation, MRZ Scanner JavaScript Edition, API, APIs +breadcrumbText: API References +description: Dynamsoft MRZ Scanner JavaScript Edition - API Reference +--- + +# MRZ Scanner JavaScript Edition API Reference + +The `MRZScanner` class is responsible for the main scanning process, including MRZ recognition, text parsing, and result display. + +## Constructor + +### MRZScanner + +#### Syntax + +```ts +new MRZScanner(config: MRZScannerConfig) +``` + +#### Parameters + +- `config`: Assigns the MRZ Scanner license and configures the different settings of the MRZ Scanner, including the container, supported MRTD formats, and more. This config object is of type [*MRZScannerConfig*](#mrzscannerconfig). + +#### Example + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + // For custom scanning configuration, MRZScannerViewConfig goes in here + }, + resultViewConfig: { + // For custom result configuration, MRZResultViewConfig goes in here + } +}); +``` + +## Methods + +### launch() + +Starts the **MRZ scanning workflow**. If the method is run without a file input, the MRZScannerView UI will pop up and allow the user to scan MRZs using their camera. Alternatively, if the method is run with a file input parameter, the MRZ Scanner will read the MRZ from the file and display the result in a `MRZResultView`. + +#### Syntax + +```ts +launch(): Promise + +launch(fileToProcess): Promise +``` + +#### Returns + +A `Promise` resolving to a `MRZResult` object. + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + try { + const result = await mrzScanner.launch(); + console.log(result); // print the MRZResult to the console + } catch (error){ + console.error(error); + } +})(); +``` + +```ts +(async () => { + // Launch the scanner and wait for the result + try { + const result = await mrzScanner.launch(fileToProcess); + console.log(result); // print the MRZResult to the console + } catch (error){ + console.error("Error processing file:", error); + } +})(); +``` + +### dispose() + +Cleans up the MRZ Scanner resources and hides UI components. + +#### Syntax + +```ts +dispose(): void +``` + +#### Example + +```ts +mrzScanner.dispose(); +console.log("Scanner resources released."); +``` + +## Configuration Interfaces + +### MRZScannerConfig + +The **MRZScannerConfig** is responsible for assigning the MRZ Scanner license, configuring the MRTD formats, and setting the MRZScannerViewConfig and MRZResultViewConfig. Please note that the only thing that is **required** to be defined is the **license**. A MRZ Scanner instance **must** be initialized with a MRZScannerConfig object. + +To get the full picture on how to use *MRZScannerConfig*, please visit the [Customizing MRZ Scanner - MRZScannerConfig]({{ site.guides }}mrz-scanner-customization.html#mrzscannerconfig-overview) page. + +#### Syntax + +```ts +interface MRZScannerConfig { + license?: string; // license is absolutely required to be set at initialization + container?: HTMLElement | string; // + + // Resource/Template specific configuration + templateFilePath?: string; + utilizedTemplateNames?: UtilizedTemplateNames; + engineResourcePaths?: EngineResourcePaths; + + // Views Configuration + scannerViewConfig?: Omit; + resultViewConfig?: MRZResultViewConfig; + + mrzFormatType?: Array; + showResultView?: boolean; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `license` | `string` | The license key for using the `MRZScanner`. | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZScanner` UI. | +| `templateFilePath` | `string` | The file path to the custom JSON template used to customize the scanning process. | +| `utilizedTemplateNames` | `UtilizedTemplateNames` | Specifies MRZ scanning templates. | +| `engineResourcePaths` | `EngineResourcePaths` | Paths to the necessary resources for the MRZ scanning engine. | +| `scannerViewConfig` | [`MRZScannerViewConfig`](#mrzscannerviewconfig) | Configuration settings for the MRZ scanner view. | +| `resultViewConfig` | [`MRZResultViewConfig`](#mrzresultviewconfig) | Configuration settings for the MRZ result view. | +| `mrzFormatType` | [`EnumMRZDocumentType`]({{ site.api }}enums-mrz-scanner.html#enummrzdocumenttype) | Specifies the MRTD formats that the application will support. | +| `showResultView` | `boolean` | Determines whether the final result view (MRZResultView) will be shown or not. | + +#### Example + +```ts +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + mrzFormatType: ["passport", "td1"], // set the MRTD formats to just passport and ID (TD1) + showResultView: false, // hide the final MRZResultView and go back to landing page once the MRZ result is in + // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference + engineResourcePaths: { + std: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std/dist/", + dip: "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing/dist/", + core: "https://cdn.jsdelivr.net/npm/dynamsoft-core/dist/", + license: "https://cdn.jsdelivr.net/npm/dynamsoft-license/dist/", + cvr: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router/dist/", + dlr: "https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer/dist/", + dcp: "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser/dist/", + }, + scannerViewConfig: { + // the MRZScannerViewConfig goes in here - see MRZScannerViewConfig section + }, + resultViewConfig: { + // the MRZResultViewConfig goes in here - see MRZResultViewConfig section + } +}; + +// Initialize the Dynamsoft MRZ Scanner with the above MRZScannerConfig object +const mrzScanner = new Dynamsoft.MRZScanner(mrzConfig); +``` + +### MRZScannerViewConfig + +The MRZScannerViewConfig is used to configure the UI elements of the **MRZScannerView**. If the MRZScannerViewConfig is not assigned, then the library will use the default MRZScannerView. For the full details of the properties of the MRZScannerViewConfig, please read through the [Customizing the MRZ Scanner - MRZScannerViewConfig]({{ site.guides }}mrz-scanner-customization.html#mrzscannerviewconfig-overview) page. + +#### Syntax + +```ts +interface MRZScannerViewConfig { + cameraEnhancerUIPath?: string; + container?: HTMLElement | string; + + showScanGuide?: boolean; + showUploadImage?: boolean; + showFormatSelector?: boolean; + showSoundToggle?: boolean; + + enableMultiFrameCrossFilter?: boolean; // false by default + + uploadAcceptedTypes?: string; + uploadFileConverter?: (file: File) => Promise; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `uiPath` | `string` | Path to the custom Camera Enhancer UI (`.html` template file) for the scanner view. | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZScannerView` UI. | +| `showScanGuide` | `boolean` | Determines whether the scan guide frame will be displayed or not. | +| `showUploadImage` | `boolean` | Determines the visibility of the "load image" icon to allow the user to select a static image from their local photo library. | +| `showFormatSelector` | `boolean` | Determines the visibility of the format selector box that allows the user to restrict the MRTD format(s) that are being read. | +| `showSoundToggle` | `boolean` | Determines the visibility of the "sound" icon that allows the user to play a beep sound once the MRZ is recognized. | +| `enableMultiFrameCrossFilter` | `boolean` | Enables or disables the MultiFrameResultCrossFilter that can improve the accuracy of the MRZ result, but possibly at the cost of speed. | +| `uploadAcceptedTypes` | `string` | Configures which image and file format(s) the library will accept if the user chooses to decode static images. | +| `uploadFileConverter` | `function` | Converts non-image files (e.g. PDF) to blobs so that they can be read by the MRZ Scanner. | + +#### Example + +```ts +const mrzScanViewConfig = { + showScanGuide: true, // hides the scan guide frame; true by default + showUploadImage: true, // hides the load image icon that shows up in the toolbar at the top of the view; true by default + showFormatSelector: true, // hides the format selector box if more than two MRZ types are assigned; true by default + showSoundToggle: false, // hides the sound icon that allows the user to control whether a beep is played once an MRZ is recognized; true by default + showPoweredByDynamsoft?: boolean; // hides the "Powered By Dynamsoft" message that appears on the scanner UI; true by default + enableMultiFrameCrossFilter: true, // turning the filter off could improve the speed but at the cost of result accuracy; true by default + + uploadAcceptedTypes: "image/*,application/pdf", // allows the user to upload static images and PDFs to be read by the MRZ Scanner - default is "image/*" + uploadFileConverter: async (file) => { + if (file.type === "application/pdf") { + // Example PDF to image conversion + const pdfData = await convertPDFToImage(file); + return pdfData; + } + + // For other non-image types, you can add more conversion logic + // If it's not a supported type, throw an error + throw new Error("Unsupported file type"); + }, +}; + +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: mrzScanViewConfig +}; +``` + +### MRZResultViewConfig + +The MRZResultViewConfig is used to configure the UI elements of the **MRZResultView**. If the MRZResultViewConfig is not assigned, then the library will use the default MRZResultView. For the full details of the properties of the MRZResultViewConfig, please read through the [Customizing the MRZ Scanner - MRZResultViewConfig]({{ site.guides }}mrz-scanner-customization.html#mrzresultviewconfig-overview) page. + +#### Syntax + +```ts +interface MRZResultViewConfig { + container?: HTMLElement | string; + toolbarButtonsConfig?: MRZResultViewToolbarButtonsConfig; + showOriginalImage?: boolean; + allowResultEditing?: boolean; // New option to control if result fields can be edited + showMRZText?: boolean; + + onDone?: (result: MRZResult) => Promise; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `container` | `HTMLElement \ string` | The container element or selector for the `MRZResultView` UI. | +| `toolbarButtonsConfig` | `MRZResultViewToolbarButtonsConfig` | Configures the main bottom toolbar of the result view. | +| `showOriginalImage` | `boolean` | Determines whether the cropped image of the MRZ document will be displayed in the result view or not. | +| `allowResultEditing` | `boolean` | Enables/disables the ability to edit the MRZ info after it is scanned. | +| `showMRZText` | `boolean` | Shows/hides the raw MRZ text as one of the fields in the result view. | +| `onDone` | `Promise` | Defines the action(s) to take once the user clicks the "Done" button in the result view. | + +#### Example + +```ts +const mrzResultViewConfig = { + showOriginalImage: false, // Hides the cropped image of the MRZ document in the result view; true by default + allowResultEditing: true, // Allows the user to manually edit the text of the parsed result fields; false by default + showMRZText: false, // Hides the raw MRZ text as a field in the result view; true by default + toolbarButtonsConfig: { + retake: { + label: "Re-scan", // Changes the text label of the retake button to "Re-scan"; string is "Re-take" by default + isHidden: true // Hides the retake button; false by default + }, + done: { + label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default + isHidden: false // Hides the done button; false by default + } + }, + /* onDone is a callback that allows you to define the action(s) to take once the user clicks the Done button and the scanner is closed. By default, nothing happens and the app goes back to the landing page. */ + onDone: (result) => { + console.log(result.status.message); + console.log(result.data.firstName); + }, +}; + +const mrzConfig = { + license: "YOUR_LICENSE_KEY_HERE", + resultViewConfig: mrzResultViewConfig +}; +``` + +### MRZResultViewToolbarButtonsConfig + +The `MRZResultViewToolbarButtonsConfig` is used to configure the buttons of the toolbar in the **MRZResultView**. + +#### Syntax + +```ts +interface MRZResultViewToolbarButtonsConfig { + retake?: ToolbarButtonConfig; + done?: ToolbarButtonConfig; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `retake` | [`ToolbarButtonConfig`](#toolbarbuttonconfig) | Configuration for the re-scan button of the toolbar. | +| `done` | [`ToolbarButtonConfig`](#toolbarbuttonconfig) | Configuration for the done button of the toolbar. | + +#### Example + +```ts +const mrzButtonConfig = { + retake: { + label: "Re-scan", + isHidden: false + }, + done: { + label: "Return Home", + isHidden: false + } +}; + +const mrzResultViewConfig = { + toolbarButtonsConfig: mrzButtonConfig, +}; +``` + +### ToolbarButtonConfig + +The interface used to configure the properties of the toolbar button. This interface is typically used in conjunction with the `MRZResultViewToolbarButtonsConfig`. + +#### Syntax + +```ts +export interface ToolbarButtonConfig { + icon: string; + label: string; + className?: string; + isHidden?: boolean; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `icon` | `string` | The path to a custom icon (png/svg) for the button. | +| `label` | `string` | The text label of the button. | +| `className` | `string` | Assigns a custom class to the button (usually to apply custom styling). | +| `isHidden` | `boolean` | Hides/Shows the button in the toolbar. | + +#### Example + +See the [example of `MRZResultViewToolbarButtonsConfig`](#example-6). + +## Result Interfaces + +### MRZResult + +The MRZResult is the most basic interface that is used to represent the full MRZ result object. It comes with a result status, the original cropped image result, and the parsed MRZ info as a [`MRZData`](#mrzdata) object. + +#### Syntax + +```ts +export interface MRZResult { + status: ResultStatus; + originalImageResult?: DSImageData; + data?: MRZData; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `status` | [`ResultStatus`](#resultstatus) | The status of the MRZ result, which can be successful, cancelled (if the user closes the scanner), or failed (indicating that something has gone wrong during the scanning process). | +| `originalImageResult` | [`DSImageData`]({{ site.dcvb_js_api }}core/basic-structures/ds-image-data.html) | A `DSImageData` object that represents the cropped image of the MRZ document. | +| `data` | [`MRZData`](#mrzdata) | Represents the parsed MRZ info. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.status.message); // prints the result status message to the console + console.log(result.status.code); // prints the result status code to the console + console.log(result.data); // prints the entire MRZData object of the result to the console +})(); +``` + +### MRZData + +MRZData is used to represent the parsed fields of the MRZ result. These fields include the first name, last name, sex, document number, and more. + +#### Syntax + +```ts +export interface MRZData { + [EnumMRZData.InvalidFields]?: EnumMRZData[]; //invalidFields + [EnumMRZData.DocumentType]: string; // documentType + [EnumMRZData.DocumentNumber]: string; // documentNumber + [EnumMRZData.MRZText]: string; // mrzText + [EnumMRZData.FirstName]: string; // firstName + [EnumMRZData.LastName]: string; // lastName + [EnumMRZData.Age]: number; // age + [EnumMRZData.Sex]: string; // sex + [EnumMRZData.IssuingState]: string; // issuingState + [EnumMRZData.IssuingStateRaw]: string; //issuingStateRaw + [EnumMRZData.Nationality]: string; // nationality + [EnumMRZData.NationalityRaw]: string; //nationalityRaw + [EnumMRZData.DateOfBirth]: MRZDate; // dateOfBirth + [EnumMRZData.DateOfExpiry]: MRZDate; // dateOfExpiry +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `documentType` | `string` | The type of MRTD that the MRZ document is. | +| `documentNumber` | `string` | The MRZ document number. | +| `mrzText` | `string` | The raw unparsed text of the MRZ. | +| `firstName` | `string` | The first name of the MRZ document holder. | +| `lastName` | `string` | The last name of the MRZ document holder. | +| `age` | `string` | The age of the MRZ document holder. | +| `sex` | `string` | The sex of the MRZ document holder. | +| `issuingState` | `string` | The issuing state (represented as the full name of the country/region) of the MRZ document. | +| `issuingStateRaw` | `string` | The raw text from the MRZ string of the issuing state of the MRZ document. | +| `nationality` | `string` | The nationality (represented as the full name of the country/region) of the MRZ document holder. | +| `nationalityRaw` | `string` | The raw text from the MRZ string representing the nationality of the document holder. | +| `dateOfBirth` | [`MRZDate`](#mrzdate) | The date of birth of the MRZ document holder. | +| `dateOfExpiry` | [`MRZDate`](#mrzdate) | The date of expiry of the MRZ document. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.data.firstName); // prints the first name + console.log(result.data.lastName); // prints the last name + console.log(result.data.sex); // prints the sex + console.log(result.data.nationality); // prints the nationality + console.log(result.data.documentNumber); // prints the MRZ document number +})(); +``` + +### MRZDate + +MRZDate is used to represent the date fields of a `MRZData` object. + +#### Syntax + +```ts +interface MRZDate { + year: number; + month: number; + day: number; +} +``` + +#### Properties + +| Property | Type | Description | +| ----------------------- | ------------------------------ | --------------------------------------------------------------- | +| `year` | `number` | The year of the date. | +| `month` | `number` | The month of the date. | +| `day` | `number` | The day of the date. | + +#### Example + +```ts +(async () => { + // Launch the scanner and wait for the result + const result = await mrzScanner.launch(); + console.log(result.data.dateOfBirth.year); // prints the year of the date of birth + console.log(result.data.dateOfBirth.month); // prints the month of the date of birth + console.log(result.data.dateOfBirth.day); // prints the day of the date of birth +})(); +``` + +### ResultStatus + +ResultStatus is used to represent the status of the MRZ Result. This status can be **successful**, **cancelled** if the user closes the scanner, or **failed** if something went wrong during the scanning process. The *code* of the result status is a [`EnumResultStatus`]({{ site.api }}enums-mrz-scanner.md#enumresultstatus). + +#### Syntax + +```ts +type ResultStatus = { + code: EnumResultStatus; + message?: string; +}; +``` + +#### Example + +Please see the [example of MRZResult](#example-8). diff --git a/api/mrz-scanner.md b/api/mrz-scanner.md index 48f1c4e..3270095 100644 --- a/api/mrz-scanner.md +++ b/api/mrz-scanner.md @@ -182,7 +182,7 @@ The MRZScannerViewConfig is used to configure the UI elements of the **MRZScanne ```ts interface MRZScannerViewConfig { - cameraEnhancerUIPath?: string; + uiPath?: string; container?: HTMLElement | string; showScanGuide?: boolean; @@ -304,8 +304,7 @@ const mrzResultViewConfig = { }, /* onCancel is a callback that allows you to define the action(s) that will happen once the user clicks the Cancel button which only shows up if the MRZ scanner is launched with a static file rather than with the camera view. By default, nothing happens and the app goes back to the landing page */ onCancel: (result) => { - console.log(result.status.message); - console.log(result.data.firstName); + /* implement the code to redirect the user to a new page should you not want them to go back to the landing page since that is the default behaviour */ } }; @@ -441,7 +440,9 @@ export interface MRZData { [EnumMRZData.Age]: number; // age [EnumMRZData.Sex]: string; // sex [EnumMRZData.IssuingState]: string; // issuingState + [EnumMRZData.IssuingStateRaw]: string; //issuingStateRaw [EnumMRZData.Nationality]: string; // nationality + [EnumMRZData.NationalityRaw]: string; //nationalityRaw [EnumMRZData.DateOfBirth]: MRZDate; // dateOfBirth [EnumMRZData.DateOfExpiry]: MRZDate; // dateOfExpiry } diff --git a/guides/mrz-scanner-customization-v2.0.md b/guides/mrz-scanner-customization-v2.0.md new file mode 100644 index 0000000..2f62418 --- /dev/null +++ b/guides/mrz-scanner-customization-v2.0.md @@ -0,0 +1,234 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition +keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, Customization +description: Customizing the Dynamsoft MRZ Scanner +permalink: /guides/mrz-scanner-customization-v2.0.html +--- + +# Customizing the MRZ Scanner JavaScript Edition + +>[!NOTE] +> +>Before going into the ways that you can customize the MRZ Scanner, please read the [MRZ Scanner JavaScript Edition User Guide]({{ site.guides }}mrz-scanner.html). + +## Quick Links + +- [Setting Available MRTD formats](#setting-available-mrtd-formats) +- [Hiding the Result View](#hiding-the-result-view) +- [Changing the Scan Guide Frame](#changing-the-scan-guide-frame) +- [Configuring the `onDone` Callback](#configuring-the-ondone-callback) +- [Enable Result Editing](#enable-result-editing) + +## Introduction + +This guide expands on the User Guide that explored the MRZ Scanner Hello World sample project. Here we explore ways to customize the UI as well as the performance of the MRZ Scanner. We will walk through the three main configuration interfaces - [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerconfig), [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerviewconfig), and [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzresultviewconfig). These configuration interfaces make customizing the MRZ Scanner as easy as adding or changing a few properties in the instance constructor. Every sample is a variation on the previous Hello World sample with a few additional properties defined in the configuration interfaces, and so we only show the differing portion rather than all the code. + +## `MRZScannerConfig` Overview + +The [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerconfig) interface is capable of configuring almost all customization options applicable to MRZ scanning use cases with the MRZ Scanner. The MRZ Scanner uses passes an `MRZScannerConfig` object to the constructor when creating an MRZ Scanner instance. `MRZScannerConfig` contains the following properties: + +1. **`license`** - the license key is the only property whose ***value must be specified when instantiating the MRZ Scanner instance***. If the license is undefined, invalid, or expired, the MRZ Scanner cannot proceed with scanning, and instead displays a pop-up error message instructing the user to contact the site administrator to resolve this license issue. + +2. **`container`** - pass a DOM element to this property to contain the entire MRZ Scanner UI within that DOM element. This property is optional. When not specified, (e.g. in our [Hello World sample]({{ site.codegallery }}helloworld/index.html)) the MRZ Scanner automatically creates its own container upon instantiation and uses that container instead. + +3. **`templateFilePath`** - a template file is a JSON file that contains a series of algorithm parameter settings (called Capture Vision templates) that is usually used for very specific and customized scanning and parsing scenarios. The `templateFilePath` points to the location of the JSON file. The MRZ Scanner comes with a default template file, but you may choose to use a custom template to target specialized use cases. We recommend contacting the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) for assistance with template customization. Simply host the custom template file on the hosting server of the web application and use the `templateFilePath` to define its location to the MRZ Scanner. + +4. **`utilizedTemplateNames`** - define the names of Capture Vision template(s) defined in the non-default template file pointed to by `templateFilePath`. These names must be declared in this property when using a custom template with `templateFilePath`. + +5. **`engineResourcePaths`** - the engine files of the library make up the core of the library and define the operation as well as the UI. `engineResourcePaths` defines the location of the engine files in case they are being referenced from another different location. This property is typically used with frameworks such as **React**, **Angular**, and any other framework that makes use of a package manager like **`npm`** or **`yarn`**. + +6. **`scannerViewConfig`** - this is the configuration interface for the `MRZScannerView`, which is responsible for the main scanning functionality as well as the camera UI. We explain the configuration properties nested in this object in the [`MRZScannerViewConfig` overview](#mrzscannerviewconfig-overview). + +7. **`resultViewConfig`** - this is the configuration interface for the `MRZResultView`, which is responsible for displaying the scanned MRZ document and its parsed data after a successful scan. You can find the breakdown of the `MRZResultView` settings in the [`MRZResultView` overview](#mrzresultviewconfig-overview). + +8. **`mrzFormatType`** - configure the available MRTD formats that the MRZ Scanner can read. The formats set in `mrzFormatType` are the formats that appear in the format selector box within the `MRZScannerView`. By default, the library will include all of the supported MRTD formats.To learn more about the different MRTD formats the library supports, visit the introduction page for [more details]({{ site.introduction }}index.html#supported-mrz-formats). + +9. **`showResultView`** (default value `true`) - toggle the visibility of the `MRZResultView`. If `false`, the MRZ Scanner immediately closes upon a successful scan rather than going into the `MRZResultView`, then proceeds to the next step of the web application's workflow (outside the purview of the MRZ Scanner SDK). In the case of the Hello World sample, the next step just takes the user back to the landing page. + +Next, we go over the different ways that these properties can be used to customize the scanner with a few examples. + +### Setting Available MRTD formats + +> [!TIP] +> Prerequisite: [Introduction to MRZ Formats]({{ site.introduction }}index.html#supported-mrz-formats) + +The MRZ Scanner reads all three MRZ formats, but it can optionally restrict the MRZ format that it reads. For example, you may want to configure MRZ scanner to only read **TD1** and passport (**TD3**) document types, while **ignoring TD2** documents. Here is a quick snippet based on the Hello World code (from the [User Guide]({{ site.guides }}mrz-scanner-v2.0.html)) that sets the specific MRZ formats to read using the `mrzFormatType` property: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + mrzFormatType: ["passport", "td1"], // setting it to just TD3 (passport) and TD1 +}); +``` + +After changing the `mrzFormatType`, the format selector box of the MRZScannerView reflects the two formats selected above instead of all three formats available by default. If you only set a single MRZ format with `mrzFormatType`, the format selector box of the MRZScannerView *does not appear, even if showFormatSelector is set to `true`*. + +### Hiding the Result View + +You may not want to use the Result View that the MRZ Scanner provides. If your workflow does not require the user to view or verify the scanned results, you may opt to forego the Result View after the SDK finishes a scan, then exit the MRZ Scanner portion of your application workflow. Here is how to configure the MRZScanner to hide the result view: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + showResultView: false, +}); +``` + +## `MRZScannerViewConfig` Overview + +[**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerviewconfig) controls the UI elements of the `**MRZScannerView**`, which is the view responsible for scanning operations. Here are its properties in detail: + +1. **`cameraEnhancerUIPath`** - define the path to a custom HTML user interface file for the `MRZScannerView`, which is based on the UI for the Dynamsoft Camera Enhancer SDK used by the MRZ Scanner. Setting the path to a custom file allows this custom UI to take effect for any `MRZScanner` instance created within your application. We recommend you to reach out to the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) to assist you in creating such a custom UI. + +2. **`container`** - assign a specific DOM element to contain the `MRZScannerView` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. + +3. **`showScanGuide`** (default value `true`) - toggle the availability of the *scan guide*. Other than the actual camera view, one of the main elements in the `MRZScannerView` is a *scan guide frame*. When enabled, placing the MRZ document within the boundaries of the scan guide frame allows the library to quickly and accurately recognize the MRZ and decipher it. When enabled, the MRZ Scanner does not read outside the confines of the scan guide, so enabling the scan guide reduces the need to read the entire camera frame. There are three frames, one for each MRTD format. Going from left to right, the first scan guide corresponds to the TD3 (Passport) format, the second is the TD2 (ID) format, and the third is the TD1 (ID) format. Read more about how the detection region changes with different combinations of enabled MRTD formats [here](#changing-the-scan-guide-frame). + +
    + Scan Guide Frames +
    + +4. **`showUploadImage`** (default value `true`) - in addition to scanning via a camera, the MRZ Scanner can also read MRZs from image files from the device's local storage from the file import icon in the `MRZScannerView` UI header. You can disable this feature (and the icon) by setting this property to `false`. + +5. **`showFormatSelector`** (default value `true`) - toggle the selector box near the bottom of the `MRZScannerView` that allows the user to toggle recognition of individual MRZ formats. The selectable formats in this selector box are defined by the **`mrzFormatType`** property. The user cannot disable reading all formats - at least one will be enabled. The scan guide frame (if shown) will also change based on which format(s) are selected. (see [changing the scan guide frame](#changing-the-scan-guide-frame) for more details) Setting this property to false disables the format selector. + +
    + Scan Guide Frames +
    + +6. **`showSoundToggle`** (default value `true`) - the MRZ Scanner can play a beeping sound upon successfully recognizing an MRZ. This feature depends on browser support. When this property is `true`, the sound toggle icon appears at the top of the MRZScannerView in a grey disabled state. To hide this feature altogether, set this property to `false`. + +7. **`enableMultiFrameCrossFilter`** (default value `true`) - enable the multi-frame result cross filter to improve read accuracy at the cost of a slight increase to MRZ read time. + +> [!NOTE] +> +> Not every UI element of the MRZScannerView can be controlled by the MRZScannerViewConfig. Namely, the **torch/flash button** will always show up in the **MRZScannerView**. + +### Using the MRZScannerViewConfig + +Now that we have gone through all the properties that make up the MRZScannerViewConfig, let's see them in action: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + showScanGuide: false, // hides the scan guide frame; true by default + showUploadImage: false, // hides the load image icon that shows up in the toolbar at the top of the view; true by default + showFormatSelector: false, // hides the format selector box if more than two MRZ types are assigned; true by default + showSoundToggle: false, // hides the sound icon that allows the user to control whether a beep is played once an MRZ is recognized; true by default + enableMultiFrameCrossFilter: false, // turning the filter off could improve the speed but at the cost of result accuracy; true by default + } +}); +``` + +### Changing the Scan Guide Frame + +The `MRZScannerView` provides a guide frame for each of the three MRTD formats. Because the MRZ Scanner only scans within the guide frame (when the guide frame is enabled), here we explain which guide frame is used when multiple MRTD formats are selected in the format selector: + +1. If **passport** is selected, then the guide frame for passport (TD3) will be displayed. + +2. Otherwise, if both **ID (TD1)** and **ID (TD2)** are selected or only **ID (TD1)**, (but not passport), then the frame for ID (**TD1**) will be displayed. + +3. The ID (TD2) guide frame only gets displayed if **ID (TD2)** is the only selected format. + +Please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) for any further inquiries, or to customize the frame guide selection logic. + +## `MRZResultViewConfig` Overview + +The **`MRZResultView`** user interface displays the parsed MRZ results as well as the cropped image of the MRTD document to save the time and resources needed to build your own viewer. The [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzresultviewconfig) contains the following settings used to customize this View: + +1. **`container`** - assign a specific DOM element to contain the `**MRZResultView**` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. + +2. **`toolbarButtonsConfig`** - configure the `MRZResultView` toolbar located in the footer in portrait mode, and on the right hand side of the screen in landscape. The **re-take button** takes the user back to the `MRZScannerView` to scan a new MRZ, discarding the previously scanned result. The other button is a **done button** that closes the scanner and destroys the `MRZScanner` instance. We explain how to use the `toolbarButtonsConfig` to customize this tool bar. The **cancel button** appears in place of the re-take button when the MRZ Scanner is launched with a static file instead of the standard camera UI. + +3. **`showOriginalImage`** (default value `true`) - show or hide the cropped image of the scanned MRZ document at the top of the View. Set this property to `false` to hide the image. + +4. **`showMRZText`** (default value `true`) - show or hide the raw MRZ text as one of the result fields in the result view. By default, this txt will be shown but if you would like to hide it, then setting this property to `false` will do the trick. + +5. **`allowResultEditing`** (default value `false`) - control whether or not the parsed text fields can be edited by the user. In certain cases, the MRZ text result parsed by the SDK may not exactly match the text present on the MRZ document. You may choose to allow the user to edit the result fields after cross-checking them with the info present on the document itself by displaying the original document with `showOriginalImage: true`. + +6. **`onDone`** - set a callback function to be executed upon exiting the MRZ Scanner workflow when the user clicks the *Done* button. This callback receives the MRZResult object representing the full MRZ result (including the scanned image and the parsed MRZ string) for further processing after closing the MRZ Scanner and entering the next stage of your application's workflow. Read more about implementing `onDone` in the [following section](#configuring-the-ondone-callback). + +### Using the `MRZResultViewConfig` + +Now that we have learned about the properties of the [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig) interface, let's now demonstrate how to use it in a simple code snippet: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section for details*/ + }, + resultViewConfig: { + showOriginalImage: false, // hides the cropped image of the MRZ document in the result view; true by default + allowResultEditing: true, // enables the ability to edit the result fields should the parsed information not match the MRZ document; false by default + showMRZText: false, // hides the raw MRZ text as a result field in the result view; true by default + toolbarButtonsConfig: { + retake: { + icon: "path to a png/svg file" // Changes the icon image of the retake button + label: "Re-scan", // Change the text label of the retake button to the provided string; string is "Re-take" by default + isHidden: true, // Hides the retake button; false by default + className: "custom class name" // to implement a custom css to the done button, you can assign a custom css class to the button here + }, + done: { + icon: "path to a png/svg file" // Changes the icon image of the retake button + label: "Return Home", // Change the text label of the done button to the provided string; string is "Done" by default + isHidden: true, // Hides the done button; false by default + className: "custom class name" // to implement a custom css to the done button, you can assign a custom css class to the button here + } + } + } +}); +``` + +### Configuring the `onDone` Callback + +By default, once the user clicks the *Done* button in the `MRZResultView`, the scanner closes and the user is taken back to the landing page. The `onDone` callback function defined within [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzresultviewconfig) serves to add useful behavior here, typically to connect the end of the MRZ Scanner workflow to the overall workflow of your entire web application by passing the MRZ scan result (stored as an `MRZResult` object) out of the MRZ Scanner. For example: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section to learn how to set this */ + }, + resultViewConfig: { + onDone: (result) => { + console.log(result.status.message); // print the result status message to the console + console.log(result.status.code); // print the result status code + console.log(result.data.firstName); // print the first name from the MRZ info + } + } +}); +``` + +Here, when the user clicks *Done*, the application prints the result status code, status message, and the first name from the scanned document to the console. The `MRZResult` object (named `result` in the sample) contains each parsed text field, the full MRZ text string, and the cropped image of the scanned MRZ document. You web application can rely on the MRZ Scanner to parse the MRZ string and easily use MRZ fields using the `result.data.{fieldName}` scheme as shown above. + +### Enable Result Editing + +There could be certain cases where the parsed fields in the final **MRZResultView** do not pass validation as they fail the check digit step of the parsing process. To better deal with those cases, the MRZ Scanner has the feature to allow the user to edit the result fields directly. + +By enabling this feature, users can verify the parsed information provided by the MRZ Scanner is correct compared to the information present on the MRZ document. This feature acts as a sort of safety net for any results that don't pass the validation check or if the user just wants to make sure that the parsed information from the MRZ matches the information on the MRZ document. + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section to learn how to set this */ + }, + resultViewConfig: { + allowResultEditing: false, + } +}); +``` + +By changing *allowResultEditing* in the `resultViewConfig`, the user will now see a slightly different UI in the result view. Below is a screenshot showing the UI difference + +
    + MRZ Result View Editing Feature +
    + +As you can see above, when result editing is enabled, the result fields will change into editable fields like in a form. \ No newline at end of file diff --git a/guides/mrz-scanner-customization-v2.1.md b/guides/mrz-scanner-customization-v2.1.md new file mode 100644 index 0000000..4e3ad25 --- /dev/null +++ b/guides/mrz-scanner-customization-v2.1.md @@ -0,0 +1,260 @@ +--- +layout: default-layout +needAutoGenerateSidebar: true +needGenerateH3Content: true +noTitleIndex: false +title: Dynamsoft MRZ Scanner JavaScript Edition +keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, Customization +description: Customizing the Dynamsoft MRZ Scanner +permalink: /guides/mrz-scanner-customization-v2.1.html +--- + +# Customizing the MRZ Scanner JavaScript Edition + +>[!NOTE] +> +>Before going into the ways that you can customize the MRZ Scanner, please read the [MRZ Scanner JavaScript Edition User Guide]({{ site.guides }}mrz-scanner-v2.1.html). + +## Quick Links + +- [Setting Available MRTD formats](#setting-available-mrtd-formats) +- [Hiding the Result View](#hiding-the-result-view) +- [Changing the Scan Guide Frame](#changing-the-scan-guide-frame) +- [Reading Static Images and PDFs using the MRZ Scanner](#reading-static-images-and-pdfs-using-the-mrz-scanner) +- [Configuring the `onDone` Callback](#configuring-the-ondone-callback) +- [Enable Result Editing](#enable-result-editing) + +## Introduction + +This guide expands on the User Guide that explored the MRZ Scanner Hello World sample project. Here we explore ways to customize the UI as well as the performance of the MRZ Scanner. We will walk through the three main configuration interfaces - [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerconfig), [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerviewconfig), and [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig). These configuration interfaces make customizing the MRZ Scanner as easy as adding or changing a few properties in the instance constructor. Every sample is a variation on the previous Hello World sample with a few additional properties defined in the configuration interfaces, and so we only show the differing portion rather than all the code. + +## `MRZScannerConfig` Overview + +The [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerconfig) interface is capable of configuring almost all customization options applicable to MRZ scanning use cases with the MRZ Scanner. The MRZ Scanner uses passes an `MRZScannerConfig` object to the constructor when creating an MRZ Scanner instance. `MRZScannerConfig` contains the following properties: + +1. **`license`** - the license key is the only property whose ***value must be specified when instantiating the MRZ Scanner instance***. If the license is undefined, invalid, or expired, the MRZ Scanner cannot proceed with scanning, and instead displays a pop-up error message instructing the user to contact the site administrator to resolve this license issue. + +2. **`container`** - pass a DOM element to this property to contain the entire MRZ Scanner UI within that DOM element. This property is optional. When not specified, (e.g. in our [Hello World sample]({{ site.codegallery }}helloworld/index.html)) the MRZ Scanner automatically creates its own container upon instantiation and uses that container instead. + +3. **`templateFilePath`** - a template file is a JSON file that contains a series of algorithm parameter settings (called Capture Vision templates) that is usually used for very specific and customized scanning and parsing scenarios. The `templateFilePath` points to the location of the JSON file. The MRZ Scanner comes with a default template file, but you may choose to use a custom template to target specialized use cases. We recommend contacting the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) for assistance with template customization. Simply host the custom template file on the hosting server of the web application and use the `templateFilePath` to define its location to the MRZ Scanner. + +4. **`utilizedTemplateNames`** - define the names of Capture Vision template(s) defined in the non-default template file pointed to by `templateFilePath`. These names must be declared in this property when using a custom template with `templateFilePath`. + +5. **`engineResourcePaths`** - the engine files of the library make up the core of the library and define the operation as well as the UI. `engineResourcePaths` defines the location of the engine files in case they are being referenced from another different location. This property is typically used with frameworks such as **React**, **Angular**, and any other framework that makes use of a package manager like **`npm`** or **`yarn`**. + +6. **`scannerViewConfig`** - this is the configuration interface for the `MRZScannerView`, which is responsible for the main scanning functionality as well as the camera UI. We explain the configuration properties nested in this object in the [`MRZScannerViewConfig` overview](#mrzscannerviewconfig-overview). + +7. **`resultViewConfig`** - this is the configuration interface for the `MRZResultView`, which is responsible for displaying the scanned MRZ document and its parsed data after a successful scan. You can find the breakdown of the `MRZResultView` settings in the [`MRZResultView` overview](#mrzresultviewconfig-overview). + +8. **`mrzFormatType`** - configure the available MRTD formats that the MRZ Scanner can read. The formats set in `mrzFormatType` are the formats that appear in the format selector box within the `MRZScannerView`. By default, the library will include all of the supported MRTD formats.To learn more about the different MRTD formats the library supports, visit the introduction page for [more details]({{ site.introduction }}index.html#supported-mrz-formats). + +9. **`showResultView`** (default value `true`) - toggle the visibility of the `MRZResultView`. If `false`, the MRZ Scanner immediately closes upon a successful scan rather than going into the `MRZResultView`, then proceeds to the next step of the web application's workflow (outside the purview of the MRZ Scanner SDK). In the case of the Hello World sample, the next step just takes the user back to the landing page. + +Next, we go over the different ways that these properties can be used to customize the scanner with a few examples. + +### Setting Available MRTD formats + +> [!TIP] +> Prerequisite: [Introduction to MRZ Formats]({{ site.introduction }}index.html#supported-mrz-formats) + +The MRZ Scanner reads all three MRZ formats, but it can optionally restrict the MRZ format that it reads. For example, you may want to configure MRZ scanner to only read **TD1** and passport (**TD3**) document types, while **ignoring TD2** documents. Here is a quick snippet based on the Hello World code (from the [User Guide]({{ site.guides }}mrz-scanner-v2.1.html)) that sets the specific MRZ formats to read using the `mrzFormatType` property: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + mrzFormatType: ["passport", "td1"], // setting it to just TD3 (passport) and TD1 +}); +``` + +After changing the `mrzFormatType`, the format selector box of the MRZScannerView reflects the two formats selected above instead of all three formats available by default. If you only set a single MRZ format with `mrzFormatType`, the format selector box of the MRZScannerView *does not appear, even if showFormatSelector is set to `true`*. + +### Hiding the Result View + +You may not want to use the Result View that the MRZ Scanner provides. If your workflow does not require the user to view or verify the scanned results, you may opt to forego the Result View after the SDK finishes a scan, then exit the MRZ Scanner portion of your application workflow. Here is how to configure the MRZScanner to hide the result view: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + showResultView: false, +}); +``` + +## `MRZScannerViewConfig` Overview + +[**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerviewconfig) controls the UI elements of the `**MRZScannerView**`, which is the view responsible for scanning operations. Here are its properties in detail: + +1. **`cameraEnhancerUIPath`** - define the path to a custom HTML user interface file for the `MRZScannerView`, which is based on the UI for the Dynamsoft Camera Enhancer SDK used by the MRZ Scanner. Setting the path to a custom file allows this custom UI to take effect for any `MRZScanner` instance created within your application. We recommend you to reach out to the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) to assist you in creating such a custom UI. + +2. **`container`** - assign a specific DOM element to contain the `MRZScannerView` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. + +3. **`showScanGuide`** (default value `true`) - toggle the availability of the *scan guide*. Other than the actual camera view, one of the main elements in the `MRZScannerView` is a *scan guide frame*. When enabled, placing the MRZ document within the boundaries of the scan guide frame allows the library to quickly and accurately recognize the MRZ and decipher it. When enabled, the MRZ Scanner does not read outside the confines of the scan guide, so enabling the scan guide reduces the need to read the entire camera frame. There are three frames, one for each MRTD format. Going from left to right, the first scan guide corresponds to the TD3 (Passport) format, the second is the TD2 (ID) format, and the third is the TD1 (ID) format. Read more about how the detection region changes with different combinations of enabled MRTD formats [here](#changing-the-scan-guide-frame). + +
    + Scan Guide Frames +
    + +4. **`showUploadImage`** (default value `true`) - in addition to scanning via a camera, the MRZ Scanner can also read MRZs from image files from the device's local storage from the file import icon in the `MRZScannerView` UI header. You can disable this feature (and the icon) by setting this property to `false`. + +5. **`showFormatSelector`** (default value `true`) - toggle the selector box near the bottom of the `MRZScannerView` that allows the user to toggle recognition of individual MRZ formats. The selectable formats in this selector box are defined by the **`mrzFormatType`** property. The user cannot disable reading all formats - at least one will be enabled. The scan guide frame (if shown) will also change based on which format(s) are selected. (see [changing the scan guide frame](#changing-the-scan-guide-frame) for more details) Setting this property to false disables the format selector. + +
    + Scan Guide Frames +
    + +6. **`showSoundToggle`** (default value `true`) - the MRZ Scanner can play a beeping sound upon successfully recognizing an MRZ. This feature depends on browser support. When this property is `true`, the sound toggle icon appears at the top of the MRZScannerView in a grey disabled state. To hide this feature altogether, set this property to `false`. + +7. **`showPoweredByDynamsoft`** (default value `true`) - the scanner UI includes a "Powered By Dynamsoft" message that shows at the bottom. This property allows you to hide this text if you wish. + +8. **`enableMultiFrameCrossFilter`** (default value `true`) - enable the multi-frame result cross filter to improve read accuracy at the cost of a slight increase to MRZ read time. + +9. **`uploadAcceptedTypes`** (default value `"image/*"`) - allows the user to configure which image and file format(s) the library will accept if the user chooses to decode static images instead of using the camera view to scan MRZs. + +10. **`uploadFileConverter`** - this function converts non-image files (e.g. PDF) to blobs so that they can be read by the MRZ Scanner. It is essential that this function is used if you would like to support reading PDF files in your web app. + +> [!NOTE] +> +> Not every UI element of the MRZScannerView can be controlled by the MRZScannerViewConfig. Namely, the **torch/flash button** will always show up in the **MRZScannerView**. + +### Using the MRZScannerViewConfig + +Now that we have gone through all the properties that make up the MRZScannerViewConfig, let's see them in action: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + showScanGuide: false, // hides the scan guide frame; true by default + showUploadImage: false, // hides the load image icon that shows up in the toolbar at the top of the view; true by default + showFormatSelector: false, // hides the format selector box if more than two MRZ types are assigned; true by default + showSoundToggle: false, // hides the sound icon that allows the user to control whether a beep is played once an MRZ is recognized; true by default + showPoweredByDynamsoft: false, // hides the "Powered By Dynamsoft" message that appears on the scanner UI; true by default + enableMultiFrameCrossFilter: false, // turning the filter off could improve the speed but at the cost of result accuracy; true by default + + uploadAcceptedTypes: "image/*,application/pdf", // allows the user to upload static images and PDFs to be read by the MRZ Scanner - default is "image/*" + uploadFileConverter: async (file) => { + if (file.type === "application/pdf") { + // Example PDF to image conversion + const pdfData = await convertPDFToImage(file); + return pdfData; + } + // For other non-image types, you can add more conversion logic + // If it's not a supported type, throw an error + throw new Error("Unsupported file type"); + }, + } +}); +``` + +### Changing the Scan Guide Frame + +The `MRZScannerView` provides a guide frame for each of the three MRTD formats. Because the MRZ Scanner only scans within the guide frame (when the guide frame is enabled), here we explain which guide frame is used when multiple MRTD formats are selected in the format selector: + +1. If **passport** is selected, then the guide frame for passport (TD3) will be displayed. + +2. Otherwise, if both **ID (TD1)** and **ID (TD2)** are selected or only **ID (TD1)**, (but not passport), then the frame for ID (**TD1**) will be displayed. + +3. The ID (TD2) guide frame only gets displayed if **ID (TD2)** is the only selected format. + +Please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) for any further inquiries, or to customize the frame guide selection logic. + +### Reading Static Images and PDFs using the MRZ Scanner + +Starting from **v2.1** of the MRZ Scanner, the library is now able to read MRZs **directly** from static images and PDFs. To support this, the MRZScannerViewConfig will need to be configured to support that, especially for PDFs. + +To learn more on how to create a web application that supports static image/PDF reading using the MRZ Scanner, please refer to this [guide]({{ site.guides }}mrz-scanner-static-image.html). Furthermore, please refer to the full File Input Sample that the previously linked guide walks you through. + +## `MRZResultViewConfig` Overview + +The **`MRZResultView`** user interface displays the parsed MRZ results as well as the cropped image of the MRTD document to save the time and resources needed to build your own viewer. The [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig) contains the following settings used to customize this View: + +1. **`container`** - assign a specific DOM element to contain the `**MRZResultView**` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. + +2. **`toolbarButtonsConfig`** - configure the `MRZResultView` toolbar located in the footer in portrait mode, and on the right hand side of the screen in landscape. The **re-take button** takes the user back to the `MRZScannerView` to scan a new MRZ, discarding the previously scanned result. The other button is a **done button** that closes the scanner and destroys the `MRZScanner` instance. We explain how to use the `toolbarButtonsConfig` to customize this tool bar. The **cancel button** appears in place of the re-take button when the MRZ Scanner is launched with a static file instead of the standard camera UI. + +3. **`showOriginalImage`** (default value `true`) - show or hide the cropped image of the scanned MRZ document at the top of the View. Set this property to `false` to hide the image. + +4. **`showMRZText`** (default value `true`) - show or hide the raw MRZ text as one of the result fields in the result view. By default, this txt will be shown but if you would like to hide it, then setting this property to `false` will do the trick. + +5. **`allowResultEditing`** (default value `false`) - control whether or not the parsed text fields can be edited by the user. In certain cases, the MRZ text result parsed by the SDK may not exactly match the text present on the MRZ document. You may choose to allow the user to edit the result fields after cross-checking them with the info present on the document itself by displaying the original document with `showOriginalImage: true`. + +6. **`onDone`** - set a callback function to be executed upon exiting the MRZ Scanner workflow when the user clicks the *Done* button. This callback receives the MRZResult object representing the full MRZ result (including the scanned image and the parsed MRZ string) for further processing after closing the MRZ Scanner and entering the next stage of your application's workflow. Read more about implementing `onDone` in the [following section](#configuring-the-ondone-callback). + +### Using the `MRZResultViewConfig` + +Now that we have learned about the properties of the [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig) interface, let's now demonstrate how to use it in a simple code snippet: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section for details*/ + }, + resultViewConfig: { + showOriginalImage: false, // hides the cropped image of the MRZ document in the result view; true by default + allowResultEditing: true, // enables the ability to edit the result fields should the parsed information not match the MRZ document; false by default + showMRZText: false, // hides the raw MRZ text as a result field in the result view; true by default + toolbarButtonsConfig: { + retake: { + icon: "path to a png/svg file" // Changes the icon image of the retake button + label: "Re-scan", // Change the text label of the retake button to the provided string; string is "Re-take" by default + isHidden: true, // Hides the retake button; false by default + className: "custom class name" // to implement a custom css to the done button, you can assign a custom css class to the button here + }, + done: { + icon: "path to a png/svg file" // Changes the icon image of the retake button + label: "Return Home", // Change the text label of the done button to the provided string; string is "Done" by default + isHidden: true, // Hides the done button; false by default + className: "custom class name" // to implement a custom css to the done button, you can assign a custom css class to the button here + } + } + } +}); +``` + +### Configuring the `onDone` Callback + +By default, once the user clicks the *Done* button in the `MRZResultView`, the scanner closes and the user is taken back to the landing page. The `onDone` callback function defined within [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig) serves to add useful behavior here, typically to connect the end of the MRZ Scanner workflow to the overall workflow of your entire web application by passing the MRZ scan result (stored as an `MRZResult` object) out of the MRZ Scanner. For example: + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section to learn how to set this */ + }, + resultViewConfig: { + onDone: (result) => { + console.log(result.status.message); // print the result status message to the console + console.log(result.status.code); // print the result status code + console.log(result.data.firstName); // print the first name from the MRZ info + } + } +}); +``` + +Here, when the user clicks *Done*, the application prints the result status code, status message, and the first name from the scanned document to the console. The `MRZResult` object (named `result` in the sample) contains each parsed text field, the full MRZ text string, and the cropped image of the scanned MRZ document. You web application can rely on the MRZ Scanner to parse the MRZ string and easily use MRZ fields using the `result.data.{fieldName}` scheme as shown above. + +### Enable Result Editing + +There could be certain cases where the parsed fields in the final **MRZResultView** do not pass validation as they fail the check digit step of the parsing process. To better deal with those cases, the MRZ Scanner has the feature to allow the user to edit the result fields directly. + +By enabling this feature, users can verify the parsed information provided by the MRZ Scanner is correct compared to the information present on the MRZ document. This feature acts as a sort of safety net for any results that don't pass the validation check or if the user just wants to make sure that the parsed information from the MRZ matches the information on the MRZ document. + +```ts +const mrzScanner = new Dynamsoft.MRZScanner({ + license: "YOUR_LICENSE_KEY_HERE", + scannerViewConfig: { + /* see the MRZScannerViewConfig section to learn how to set this */ + }, + resultViewConfig: { + allowResultEditing: false, + } +}); +``` + +By changing *allowResultEditing* in the `resultViewConfig`, the user will now see a slightly different UI in the result view. Below is a screenshot showing the UI difference + +
    + MRZ Result View Editing Feature +
    + +As you can see above, when result editing is enabled, the result fields will change into editable fields like in a form. \ No newline at end of file diff --git a/guides/mrz-scanner-customization.md b/guides/mrz-scanner-customization.md index 8a3f72e..a881639 100644 --- a/guides/mrz-scanner-customization.md +++ b/guides/mrz-scanner-customization.md @@ -34,7 +34,7 @@ The [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) in 1. **`license`** - the license key is the only property whose ***value must be specified when instantiating the MRZ Scanner instance***. If the license is undefined, invalid, or expired, the MRZ Scanner cannot proceed with scanning, and instead displays a pop-up error message instructing the user to contact the site administrator to resolve this license issue. -2. **`container`** - pass a DOM element to this property to contain the entire MRZ Scanner UI within that DOM element. This property is optional. When not specified, (e.g. in our [Hello World sample]({{ site.guides }}mrz-scanner.html#quick-start-hello-world)) the MRZ Scanner automatically creates its own container upon instantiation and uses that container instead. +2. **`container`** - pass a DOM element to this property to contain the entire MRZ Scanner UI within that DOM element. This property is optional. When not specified, (e.g. in our [Hello World sample]({{ site.codegallery }}helloworld/index.html)) the MRZ Scanner automatically creates its own container upon instantiation and uses that container instead. 3. **`templateFilePath`** - a template file is a JSON file that contains a series of algorithm parameter settings (called Capture Vision templates) that is usually used for very specific and customized scanning and parsing scenarios. The `templateFilePath` points to the location of the JSON file. The MRZ Scanner comes with a default template file, but you may choose to use a custom template to target specialized use cases. We recommend contacting the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) for assistance with template customization. Simply host the custom template file on the hosting server of the web application and use the `templateFilePath` to define its location to the MRZ Scanner. @@ -83,7 +83,7 @@ const mrzScanner = new Dynamsoft.MRZScanner({ [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) controls the UI elements of the `**MRZScannerView**`, which is the view responsible for scanning operations. Here are its properties in detail: -1. **`cameraEnhancerUIPath`** - define the path to a custom HTML user interface file for the `MRZScannerView`, which is based on the UI for the Dynamsoft Camera Enhancer SDK used by the MRZ Scanner. Setting the path to a custom file allows this custom UI to take effect for any `MRZScanner` instance created within your application. We recommend you to reach out to the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) to assist you in creating such a custom UI. +1. **`uiPath`** (formerly `cameraEnhancerUIPath`) - define the path to a custom HTML user interface file for the `MRZScannerView`, which is based on the UI for the Dynamsoft Camera Enhancer SDK used by the MRZ Scanner. Setting the path to a custom file allows this custom UI to take effect for any `MRZScanner` instance created within your application. We recommend you to reach out to the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) to assist you in creating such a custom UI. 2. **`container`** - assign a specific DOM element to contain the `MRZScannerView` in. By default, when not specified, the MRZScanner creates its own container for this View automatically. @@ -173,11 +173,13 @@ The **`MRZResultView`** user interface displays the parsed MRZ results as well a 3. **`showOriginalImage`** (default value `true`) - show or hide the cropped image of the scanned MRZ document at the top of the View. Set this property to `false` to hide the image. -4. **`allowResultEditing`** (default value `false`) - control whether or not the parsed text fields can be edited by the user. In certain cases, the MRZ text result parsed by the SDK may not exactly match the text present on the MRZ document. You may choose to allow the user to edit the result fields after cross-checking them with the info present on the document itself by displaying the original document with `showOriginalImage: true`. +4. **`showMRZText`** (default value `true`) - show or hide the raw MRZ text as one of the result fields in the result view. By default, this txt will be shown but if you would like to hide it, then setting this property to `false` will do the trick. -5. +5. **`allowResultEditing`** (default value `false`) - control whether or not the parsed text fields can be edited by the user. In certain cases, the MRZ text result parsed by the SDK may not exactly match the text present on the MRZ document. You may choose to allow the user to edit the result fields after cross-checking them with the info present on the document itself by displaying the original document with `showOriginalImage: true`. -5. **`onDone`** - set a callback function to be executed upon exiting the MRZ Scanner workflow when the user clicks the *Done* button. This callback receives the MRZResult object representing the full MRZ result (including the scanned image and the parsed MRZ string) for further processing after closing the MRZ Scanner and entering the next stage of your application's workflow. Read more about implementing `onDone` in the [following section](#configuring-the-ondone-callback). +6. **`onDone`** - set a callback function to be executed upon exiting the MRZ Scanner workflow when the user clicks the *Done* button. This callback receives the MRZResult object representing the full MRZ result (including the scanned image and the parsed MRZ string) for further processing after closing the MRZ Scanner and entering the next stage of your application's workflow. Read more about implementing `onDone` in the [following section](#configuring-the-ondone-callback). + +7. **`onCancel`** - set a callback function to be executed upon cancelling the MRZ Scanner process *when the scanner is launched with a static file instead of the default camera UI*. When the cancel button is clicked, the MRZ result is discarded and the user is redirected back to the landing page. However, if you wish for a different behaviour than going back to the landing page, then this callback is where you define the behaviour that you are looking to implement. Read more on how to implement this callback in the [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) section of the API reference. ### Using the `MRZResultViewConfig` @@ -192,6 +194,7 @@ const mrzScanner = new Dynamsoft.MRZScanner({ resultViewConfig: { showOriginalImage: false, // hides the cropped image of the MRZ document in the result view; true by default allowResultEditing: true, // enables the ability to edit the result fields should the parsed information not match the MRZ document; false by default + showMRZText: false, // hides the raw MRZ text as a result field in the result view; true by default toolbarButtonsConfig: { retake: { icon: "path to a png/svg file" // Changes the icon image of the retake button diff --git a/guides/mrz-scanner-v2.0.md b/guides/mrz-scanner-v2.0.md index e4bd9ec..ef6c9b4 100644 --- a/guides/mrz-scanner-v2.0.md +++ b/guides/mrz-scanner-v2.0.md @@ -6,7 +6,7 @@ noTitleIndex: false title: Dynamsoft MRZ Scanner JavaScript Edition keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, description: Dynamsoft MRZ Scanner User Guide -permalink: /guides/mrz-scanner.html +permalink: /guides/mrz-scanner-v2.0.html --- # User Guide for the MRZ Scanner JavaScript Edition @@ -33,7 +33,7 @@ The trial license can be renewed via the [customer portal](https://www.dynamsoft If you are fully satisfied with the solution and would like to move forward with a full license, please contact the [Dynamsoft Sales Team](https://www.dynamsoft.com/company/contact/). -## Quick Start - Hello World +## Quick Start - Including the Library As mentioned previously, the purpose of this guide is to help you implement a Hello World application using the MRZ Scanner solution. To showcase this, we will be using vanilla JS. You can find the full code in the [samples Github repo](https://github.com/Dynamsoft/mrz-scanner-javascript). @@ -67,7 +67,7 @@ When using a framework such as **React**, **Vue** or **Angular**, we recommend a ``` > [!WARNING] -> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. +> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. Below is the complete Hello World sample page that uses the precompiled script served via a CDN. @@ -162,7 +162,7 @@ Let's now go through the code of the Hello World sample to understand how the co Dynamsoft MRZ Scanner - Hello World - + @@ -172,7 +172,7 @@ Let's now go through the code of the Hello World sample to understand how the co ``` -The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---hello-world) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: +The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---including-the-library) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it creates a container which it populates with the **Ready-to-Use UI**. @@ -191,7 +191,7 @@ MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it ``` -Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. +Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. ### Step 3: Launching the MRZ Scanner @@ -209,21 +209,21 @@ Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api } ``` -Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: +Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: #### `MRZScannerView` -The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), which is composed of the following UI elements: +The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerviewconfig), which is composed of the following UI elements: 1. **Camera View**: The Camera View is the camera viewfinder UI component within the `MRZScannerView`. This viewfinder occupies the majority of the space within the MRZScannerView to give the user a clear view and precise control of the image being scanned. -2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame. +2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame.
    Scan Guide Frames

    -3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page. +3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page.
    Scan Guide Frames @@ -240,11 +240,11 @@ The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.ap 8. **Close Scanner Button**: This button closes the MRZ Scanner and takes the user back to the landing page. > [!NOTE] -> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. +> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization-v2.0.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. #### `MRZResultView` -Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig): +Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.0.html#mrzresultviewconfig): 1. **Original Image**: A cropped image of the scanned MRZ document - this gets displayed at the top of the `MRZResultView` by default. @@ -261,5 +261,4 @@ Here is a quick breakdown of the constituent UI elements of the result view, con Now that you got the most basic functionality of the MRZ Scanner up and running, it's time to explore the many ways in which the MRZ Scanner can be used, including customization and the ability to read directly from static images and PDFs. To learn more about those two topics, please visit the following articles -- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html) -- [Setting up the MRZ Scanner for Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) \ No newline at end of file +- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization-v2.0.html) \ No newline at end of file diff --git a/guides/mrz-scanner-v2.1.md b/guides/mrz-scanner-v2.1.md index 637a5ac..7f10693 100644 --- a/guides/mrz-scanner-v2.1.md +++ b/guides/mrz-scanner-v2.1.md @@ -6,7 +6,7 @@ noTitleIndex: false title: Dynamsoft MRZ Scanner JavaScript Edition keywords: Documentation, MRZ Scanner, Dynamsoft MRZ Scanner JavaScript Edition, description: Dynamsoft MRZ Scanner User Guide -permalink: /guides/mrz-scanner.html +permalink: /guides/mrz-scanner-v2.1.html --- # User Guide for the MRZ Scanner JavaScript Edition @@ -49,25 +49,25 @@ The simplest way to include the SDK is to use either the [**jsDelivr**](https:// - jsDelivr ```html - + ``` - UNPKG ```html - + ``` When using a framework such as **React**, **Vue** or **Angular**, we recommend adding the package as a dependency using a package manager such as **npm** or **yarn**: ```sh - npm i dynamsoft-mrz-scanner@3.0.0 -E + npm i dynamsoft-mrz-scanner@2.1.0 -E # or - yarn add dynamsoft-mrz-scanner@3.0.0 -E + yarn add dynamsoft-mrz-scanner@2.1.0 -E ``` > [!WARNING] -> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. +> When using a package manager like **npm** or **yarn**, you likely need to specify the location of the engine files as a link to a CDN. Please see the [MRZScannerConfig API]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerconfig) for a code snippet on how to set the *engineResourcePaths*. Below is the complete Hello World sample page that uses the precompiled script served via a CDN. @@ -78,7 +78,7 @@ Below is the complete Hello World sample page that uses the precompiled script s Dynamsoft MRZ Scanner - Hello World - + @@ -162,7 +162,7 @@ Let's now go through the code of the Hello World sample to understand how the co Dynamsoft MRZ Scanner - Hello World - + @@ -191,7 +191,7 @@ MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it ``` -Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. +Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscanner). Note the configuration object used to set the behaviour of the MRZ Scanner instance. The single property that is **required** to be defined in this configuration object is the **license key**. Without a valid license, the MRZ Scanner view fails to launch, and the user will be met with a license key error message. Please refer to the [licensing](#license) section of the guide for instructions on acquiring a license key. ### Step 3: Launching the MRZ Scanner @@ -209,21 +209,21 @@ Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api } ``` -Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: +Now that the [**`MRZScanner`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscanner) has been initialized and configured, it is ready to be launched! Upon launch, the MRZ Scanner presents the main **`MRZScannerView`** UI in its container on the page, and is ready to start scanning. Upon scanning an MRZ (via video or static image), the MRZ Scanner then switches to the **`MRZResultView`**, which displays a cropped image of the MRZ document as well as the parsed fields of the MRZ text. Let's break down these two Views: #### `MRZScannerView` -The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), which is composed of the following UI elements: +The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerviewconfig), which is composed of the following UI elements: 1. **Camera View**: The Camera View is the camera viewfinder UI component within the `MRZScannerView`. This viewfinder occupies the majority of the space within the MRZScannerView to give the user a clear view and precise control of the image being scanned. -2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame. +2. **Scan Guide Frame**: The Scan Guide Frame is an overlay placed on top of the Camera View that guides the user to place the MRZ document in the middle of the Camera View, in order to achieve a fast and accurate scan. The guide frame is enabled **by default**, but may be hidden via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerviewconfig) interface. Note that if scan guide frame is enabled, the scanner also crops out the region outside the guide frame.
    Scan Guide Frames

    -3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page. +3. **Format Selector**: Below the scan guide frame, you will also notice a selector box that allows the user to choose which formats the MRZ Scanner should recognize. The formats that show up in the format selector are configurable via the [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerconfig) interface, while the visibility of the format selector itself is configurable via the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzscannerviewconfig) interface. To learn about MRZ formats, please refer to the [Introduction]({{ site.introduction }}index.html#supported-mrz-formats) page.
    Scan Guide Frames @@ -240,11 +240,11 @@ The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.ap 8. **Close Scanner Button**: This button closes the MRZ Scanner and takes the user back to the landing page. > [!NOTE] -> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. +> To learn more on how to customize the MRZScannerView and its corresponding UI elements, we recommend reading the [Customizaton Guide]({{ site.guides }}mrz-scanner-customization-v2.1.html) as that will shed a lot more light on how to customize the scanner UI to fit your needs. #### `MRZResultView` -Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig): +Here is a quick breakdown of the constituent UI elements of the result view, controlled by [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner-v2.1.html#mrzresultviewconfig): 1. **Original Image**: A cropped image of the scanned MRZ document - this gets displayed at the top of the `MRZResultView` by default. @@ -261,5 +261,5 @@ Here is a quick breakdown of the constituent UI elements of the result view, con Now that you got the most basic functionality of the MRZ Scanner up and running, it's time to explore the many ways in which the MRZ Scanner can be used, including customization and the ability to read directly from static images and PDFs. To learn more about those two topics, please visit the following articles -- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization.html) +- [Customizing the MRZ Scanner]({{ site.guides }}mrz-scanner-customization-v2.1.html) - [Setting up the MRZ Scanner for Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) \ No newline at end of file diff --git a/guides/mrz-scanner.md b/guides/mrz-scanner.md index 7633f40..52a4925 100644 --- a/guides/mrz-scanner.md +++ b/guides/mrz-scanner.md @@ -117,7 +117,7 @@ Alternatively, you can use other methods like `IIS` or `Apache` to serve the pro While using the pre-compiled script is the easiest way to get started with the MRZ Scanner, we do also allow you to build the MRZ Scanner SDK from source. Building from source gives you the advantage of performing in-depth SDK customization. -The MRZ Scanner is built using three constituent Dynamsoft products: [**Dynamsoft Label Recognizer**]({{ site.dlr_js }}), [**Dynamsoft Code Parser**]({{ site.dcp_js }}api-reference/code-parser-module.html?lang=javascript), and [**Dynamsoft Camera Enhancer**]({{ site.dce_js }}api-reference/index.html?lang=javascript), so any MRZ Scanner customization involves working with the foundational API of these products. +The MRZ Scanner is built using three constituent Dynamsoft products: [**Dynamsoft Label Recognizer**]({{ site.dlr_js }}api-reference/label-recognizer-module.html?lang=javascript), [**Dynamsoft Code Parser**]({{ site.dcp_js }}api-reference/code-parser-module.html?lang=javascript), and [**Dynamsoft Camera Enhancer**]({{ site.dce_js }}api-reference/index.html?lang=javascript), so any MRZ Scanner customization involves working with the foundational API of these products. The first step to building the SDK from source is retrieving the **MRZ Scanner JavaScript Edition** source files from the official [Github repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compiling them into a distributable package, and then runs a *ready-made* Hello World sample page that is already included in the repo. @@ -210,7 +210,7 @@ Let's now go through the code of the Hello World sample to understand how the co ``` -The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---hello-world) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: +The first step in setting up the HTML in the Hello World project is to include the SDK. (We discussed the two available methods to include the SDK resources in the earlier [Quick Start](#quick-start---including-the-library) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header: MRZ Scanner comes with a **Ready-to-Use UI**. When the MRZ Scanner launches, it creates a container which it populates with the **Ready-to-Use UI**. @@ -241,7 +241,7 @@ Above is the **simplest** way to initialize the [**`MRZScanner`**]({{ site.api } }); (async () => { // Launch the scanner and wait for the result - const result = await mrzscanner.launch(); + const result = await mrzScanner.launch(); console.log(result); })(); @@ -292,6 +292,8 @@ Here is a quick breakdown of the constituent UI elements of the result view, con 4. **Done Button**: This button closes the scanner and destroys the **`MRZScanner`** instance, and returns the result object containing the MRZ scan. At that point, the application goes back to the landing page. You can additionally dictate further actions upon the button click, such as allowing the user to perform some extra actions with the MRZ result, navigating to another page, passing the result object for further processing, and more. +5. **Cancel Button**: When the scanner is launched with a static file instead of using the default camera UI, this button will appear in the result view in place of the re-take button. Once this button is clicked, the MRZ result is discarded and the user returns to the landing page. You can dictate the action(s) that happen once the button is clicked using the `onCancel` callback function of the [`MRZResultViewConfig`]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) in case you do not want the user to go back to the same landing page they were on. + > [!NOTE] > In the Hello World sample, no action is taken once the Done button is clicked. The scanner closes and the user is met with an empty page. In order to open the scanner again, the user must refresh the page. You may choose to implement a more user-friendly behavior in a production environment, such as presenting the user with an option to re-open the MRZ Scanner upon closing it. diff --git a/releasenotes/index.md b/releasenotes/index.md index 5b8c1c6..84b5ab4 100644 --- a/releasenotes/index.md +++ b/releasenotes/index.md @@ -17,7 +17,7 @@ permalink: /releasenotes/index.html ## Highlighted Features - Updated the underlying Capture Vision bundle to `3.0.3001` for major improvements in reading accuracy and speed. -- Optimized the algorithm to achieve a **30% increase in read rate** as well as +- Optimized the algorithm to achieve a **30% increase in read rate** as well as a **15% increase in accuracy**. - Added support for `TD2` and `TD3` Visa. - Added a `emptyResultMessage` property to the `ResultViewConfig` interface in order to change the string message that is displayed when no result is found.