diff --git a/codegallery/helloworld/index.md b/codegallery/helloworld/index.md
index 99db6d0..c49b77b 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 a881639..8855213 100644
--- a/guides/mrz-scanner-customization.md
+++ b/guides/mrz-scanner-customization.md
@@ -3,7 +3,7 @@ layout: default-layout
needAutoGenerateSidebar: true
needGenerateH3Content: true
noTitleIndex: false
-title: Dynamsoft MRZ Scanner JavaScript Edition
+title: Customizing the 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.html
@@ -11,9 +11,8 @@ permalink: /guides/mrz-scanner-customization.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).
+> [!NOTE]
+> Before customizing the MRZ Scanner, read the [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html).
## Quick Links
@@ -26,51 +25,57 @@ permalink: /guides/mrz-scanner-customization.html
## 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.
+This guide builds on the [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html) by exploring UI and performance customization options. You'll learn to use three main configuration interfaces:
+
+- [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) - Main configuration
+- [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) - Scanner view customization
+- [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) - Result view customization
+
+These interfaces make customization straightforward—simply add or modify properties in the constructor. Each example shows only the configuration changes needed, building on the Hello World sample.
## `MRZScannerConfig` Overview
-The [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.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:
+The [**`MRZScannerConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerconfig) interface configures most customization options for MRZ scanning. The MRZ Scanner passes an `MRZScannerConfig` object to the constructor when creating an instance. It 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.
+1. **`license`** - The license key is the only property that **must be specified** when instantiating the MRZ Scanner. If the license is undefined, invalid, or expired, the scanner displays an error message instructing the user to contact the site administrator.
-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.
+2. **`container`** - Pass a DOM element to contain the entire MRZ Scanner UI. When not specified (e.g., in the [Hello World sample]({{ site.codegallery }}helloworld/index.html)), the scanner automatically creates its own container.
-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.
+3. **`templateFilePath`** - A template file is a JSON file containing algorithm parameter settings (called Capture Vision templates) for specialized scanning scenarios. The `templateFilePath` points to this file's location. The MRZ Scanner includes a default template, but you can use a custom template for specialized use cases. Contact the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) for assistance with template customization. Host the custom template file on your server and use `templateFilePath` to specify its location.
-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`.
+4. **`utilizedTemplateNames`** - Define the names of Capture Vision templates in the custom template file specified by `templateFilePath`. These names must be declared when using a custom template.
-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`**.
+5. **`engineResourcePaths`** - The engine files provide the core functionality and UI. This property defines the location of engine files when they're referenced from a different location. Typically used with frameworks like **React** or **Angular** when using package managers 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).
+6. **`scannerViewConfig`** - Configuration interface for the `MRZScannerView`, which handles the main scanning functionality and camera UI. See the [`MRZScannerViewConfig` overview](#mrzscannerviewconfig-overview) for details.
-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).
+7. **`resultViewConfig`** - Configuration interface for the `MRZResultView`, which displays the scanned MRZ document and parsed data after a successful scan. See the [`MRZResultViewConfig` overview](#mrzresultviewconfig-overview) for details.
-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).
+8. **`mrzFormatType`** - Configure the available MRTD formats for scanning. The formats set here appear in the format selector box within the `MRZScannerView`. By default, all supported MRTD formats are included. Learn more about supported formats in the [Introduction]({{ 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.
+9. **`showResultView`** (default: `true`) - Toggle the visibility of the `MRZResultView`. When `false`, the scanner immediately closes after a successful scan and proceeds to your application's next workflow step. In the Hello World sample, this returns the user 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.
+The following sections show how to use these properties to customize the scanner.
### 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.html)) that sets the specific MRZ formats to read using the `mrzFormatType` property:
+The MRZ Scanner reads all three MRZ formats by default, but you can restrict which formats to recognize. For example, to scan only **TD1** and **TD3 (Passport)** documents while ignoring **TD2**:
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
license: "YOUR_LICENSE_KEY_HERE",
- mrzFormatType: ["passport", "td1"], // setting it to just TD3 (passport) and TD1
+ mrzFormatType: ["passport", "td1"], // TD3 (passport) and TD1 only
});
```
-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`*.
+The format selector box in the MRZScannerView will reflect your selection. If you specify only a single format, the selector box 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:
+If your workflow doesn't require users to view or verify scanned results, you can hide the Result View and proceed directly to the next step:
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
@@ -83,41 +88,40 @@ 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. **`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.
+1. **`uiPath`** (formerly `cameraEnhancerUIPath`) - Specifies the path to a custom HTML user interface file for the `MRZScannerView`. The `MRZScannerView` is based on the Dynamsoft Camera Enhancer SDK UI. Contact the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/) for assistance creating custom UI files.
-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.
+2. **`container`** - Assigns a specific DOM element to contain the `MRZScannerView`. When not specified, the MRZ Scanner automatically creates its own container.
-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).
+3. **`showScanGuide`** (default: `true`) - Toggles the scan guide frame visibility. The scan guide frame is an overlay that helps users position their MRZ document correctly. When enabled, the scanner only reads within the frame boundaries, improving recognition speed and accuracy. Three frames are available, one for each MRTD format: TD3 (Passport), TD2 (ID), and TD1 (ID). See [Changing the Scan Guide Frame](#changing-the-scan-guide-frame) for details on how the frame changes based on selected formats.
-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`.
+4. **`showUploadImage`** (default: `true`) - Toggles the file import icon in the `MRZScannerView` header. When enabled, users can scan MRZs from image files stored on their device. Set to `false` to hide this feature.
-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.
+5. **`showFormatSelector`** (default: `true`) - Toggles the format selector box that appears near the bottom of the `MRZScannerView`. This selector allows users to enable or disable recognition of individual MRZ formats. Available formats are defined by the `mrzFormatType` property. At least one format must remain enabled. The scan guide frame updates based on selected formats (see [Changing the Scan Guide Frame](#changing-the-scan-guide-frame)).
-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`.
+6. **`showSoundToggle`** (default: `true`) - Toggles the sound icon that appears in the `MRZScannerView` header. When enabled, users can control whether a beep plays after successfully recognizing an MRZ. This feature depends on browser support. Set to `false` to hide the sound toggle.
-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.
+7. **`showPoweredByDynamsoft`** (default: `true`) - Toggles the "Powered By Dynamsoft" message at the bottom of the scanner UI. Set to `false` to hide this text.
-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.
+8. **`enableMultiFrameCrossFilter`** (default: `true`) - Enables the multi-frame result cross filter, which improves recognition accuracy at the cost of slightly longer scan times.
-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.
+9. **`uploadAcceptedTypes`** (default: `"image/*"`) - Specifies which image and file formats the scanner accepts when users upload static files instead of using the camera.
-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.
+10. **`uploadFileConverter`** - A function that converts non-image files (e.g., PDFs) to blobs for processing by the MRZ Scanner. This function is required to support PDF file uploads.
> [!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**.
+> The **torch/flash button** always appears in the `MRZScannerView` and cannot be hidden via configuration.
### Using the MRZScannerViewConfig
-Now that we have gone through all the properties that make up the MRZScannerViewConfig, let's see them in action:
+Here's an example showing the `MRZScannerViewConfig` properties in use:
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
@@ -147,43 +151,43 @@ const mrzScanner = new Dynamsoft.MRZScanner({
### 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:
+The `MRZScannerView` provides a guide frame for each of the three MRTD formats. When the guide frame is enabled, the scanner only reads within its boundaries. The active guide frame depends on which formats are selected:
-1. If **passport** is selected, then the guide frame for passport (TD3) will be displayed.
+1. If **Passport** is selected, the **TD3 (Passport)** guide frame displays.
-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.
+2. If both **ID (TD1)** and **ID (TD2)** are selected, or only **ID (TD1)** is selected (without Passport), the **TD1 (ID)** guide frame displays.
-3. The ID (TD2) guide frame only gets displayed if **ID (TD2)** is the only selected format.
+3. The **TD2 (ID)** guide frame only displays when **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.
+Contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) 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.
+Starting with **v2.1**, the MRZ Scanner can read MRZs directly from static images and PDFs. Configure the `MRZScannerViewConfig` properties `uploadAcceptedTypes` and `uploadFileConverter` to enable this functionality, particularly for PDF support.
-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.
+For a complete implementation guide, see [Using the MRZ Scanner with Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html), which includes a full File Input sample.
## `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.html#mrzresultviewconfig) contains the following settings used to customize this View:
+The `MRZResultView` displays parsed MRZ results and a cropped image of the MRTD document, eliminating the need to build a custom viewer. The [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) contains the following settings:
-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.
+1. **`container`** - Assigns a specific DOM element to contain the `MRZResultView`. When not specified, the MRZ Scanner automatically creates its own container.
-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.
+2. **`toolbarButtonsConfig`** - Configures the `MRZResultView` toolbar (located in the footer in portrait mode, on the right side in landscape). The toolbar includes a **re-take button** that returns to the `MRZScannerView` for a new scan (discarding the current result) and a **done button** that closes the scanner and destroys the `MRZScanner` instance. When scanning a static file instead of using the camera, a **cancel button** appears in place of the re-take button.
-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.
+3. **`showOriginalImage`** (default: `true`) - Toggles the cropped document image at the top of the result view. Set 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.
+4. **`showMRZText`** (default: `true`) - Toggles the raw MRZ text field in the result view. Set to `false` to hide this field.
-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. **`allowResultEditing`** (default: `false`) - Controls whether users can edit the parsed text fields. Enable this to allow users to correct parsed results that don't match the physical document. Combine with `showOriginalImage: true` to display the document image for cross-checking.
-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).
+6. **`onDone`** - A callback function executed when the user clicks the *Done* button. This callback receives the `MRZResult` object (including the scanned image and parsed data) for processing after the scanner closes. See [Configuring the onDone Callback](#configuring-the-ondone-callback) for implementation details.
-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.
+7. **`onCancel`** - A callback function executed when the user clicks the *Cancel* button (only appears when scanning a static file). By default, clicking cancel discards the result and returns to the landing page. Use this callback to define custom behavior. See the [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) API reference for implementation details.
### Using the `MRZResultViewConfig`
-Now that we have learned about the properties of the [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) interface, let's now demonstrate how to use it in a simple code snippet:
+Here's an example showing the `MRZResultViewConfig` properties in use:
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
@@ -215,7 +219,7 @@ const mrzScanner = new Dynamsoft.MRZScanner({
### 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.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:
+By default, clicking the *Done* button closes the scanner and returns to the landing page. The `onDone` callback in [**`MRZResultViewConfig`**]({{ site.api }}mrz-scanner.html#mrzresultviewconfig) lets you define custom behavior to integrate the scanner into your application workflow. The callback receives the `MRZResult` object containing all parsed data. For example:
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
@@ -233,13 +237,13 @@ const mrzScanner = new Dynamsoft.MRZScanner({
});
```
-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.
+In this example, clicking *Done* prints the result status, status message, and first name to the console. The `MRZResult` object contains all parsed fields, the raw MRZ text, and the cropped document image. Access parsed fields using the `result.data.{fieldName}` pattern 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.
+In some cases, parsed fields may fail validation during the check digit verification step. The result editing feature allows users to manually correct these fields by comparing them against the physical document.
-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.
+Enable this feature to let users verify and adjust parsed information when validation fails or when manual verification is required.
```ts
const mrzScanner = new Dynamsoft.MRZScanner({
@@ -248,15 +252,36 @@ const mrzScanner = new Dynamsoft.MRZScanner({
/* see the MRZScannerViewConfig section to learn how to set this */
},
resultViewConfig: {
- allowResultEditing: false,
+ allowResultEditing: true,
}
});
```
-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
+Setting `allowResultEditing: true` changes the result view UI to display editable fields. The screenshot below shows the difference:
-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
+As you can see above, when result editing is enabled, the result fields will change into editable fields like in a form.
+
+## Conclusion
+
+The MRZ Scanner JavaScript Edition provides extensive customization options to fit your specific workflow requirements. Through the three main configuration interfaces—`MRZScannerConfig`, `MRZScannerViewConfig`, and `MRZResultViewConfig`—you can control virtually every aspect of the scanner's behavior and appearance.
+
+Key customization capabilities include:
+
+- **Format Control** - Restrict scanning to specific MRTD formats based on your use case
+- **UI Customization** - Show or hide UI elements like the result view, scan guide, format selector, and toolbar buttons
+- **File Input Support** - Enable scanning from static images and PDFs in addition to camera input
+- **Result Handling** - Use the `onDone` callback to integrate scanned results into your application workflow
+- **Result Editing** - Allow users to manually correct parsed fields when validation fails
+
+These configuration options work together to create a seamless scanning experience tailored to your application's needs. For additional customization requirements or technical assistance, contact the [Dynamsoft Technical Support Team](https://www.dynamsoft.com/company/contact/).
+
+For more information about the MRZ Scanner JavaScript Edition, explore these resources:
+
+- [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html) - Getting started with basic implementation
+- [Using the MRZ Scanner with Static Images and PDFs]({{ site.guides }}mrz-scanner-static-image.html) - Complete guide for file input support
+- [API Reference]({{ site.api }}mrz-scanner.html) - Detailed documentation for all configuration interfaces
+- [Introduction]({{ site.introduction }}index.html) - Overview of MRZ formats and capabilities
\ No newline at end of file
diff --git a/guides/mrz-scanner-static-image.md b/guides/mrz-scanner-static-image.md
index 1aba913..133908f 100644
--- a/guides/mrz-scanner-static-image.md
+++ b/guides/mrz-scanner-static-image.md
@@ -9,24 +9,29 @@ description: Dynamsoft MRZ Scanner User Guide
permalink: /guides/mrz-scanner-static-image.html
---
-# Setting up the MRZ Scanner for Static Images and PDFs
+# Using the MRZ Scanner with Static Images and PDFs
-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).
+The main [MRZ Scanner User Guide]({{ site.guides }}mrz-scanner.html) demonstrates scanning MRZs from a live camera feed, including the Load Image button in the [`MRZScannerView`]({{ site.guides }}mrz-scanner.html#mrzscannerview) for selecting photos from your device.
-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.
+Starting with **v2.1**, the MRZ Scanner can read MRZs directly from static images and PDFs without requiring the default file picker. This guide shows you how to implement this functionality programmatically, supporting multiple image formats and PDF documents.
> [!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.
+> To follow along with this guide, refer to the [use-file-input sample](https://github.com/Dynamsoft/mrz-scanner-javascript/tree/main/samples/scenarios/use-file-input.html) in the MRZ Scanner GitHub repository.
## Prerequisites
-To get started with the development process, a valid license key is needed. To obtain a license key, please refer to the [Licensing]({{ site.guides }}mrz-scanner.html#license) section of the main User Guide. The next section will break down the code and take you through the sample step-by-step.
+You'll need a valid license key to get started. Refer to the [Licensing]({{ site.guides }}mrz-scanner.html#license) section of the main User Guide for instructions on obtaining one.
-## Breaking Down the Code
+## Understanding the Implementation
### Step 1: Including the Library and Defining UI Elements
-The first step in making the sample is to define the script references and the HTML elements of the page. In terms of the scripts, similar to the Hello World sample, the MRZ Scanner script needs to be referenced, either locally or via a CDN link. Since this sample will also support PDFs, we must use the [**PDF JS**](https://github.com/mozilla/pdf.js) library. Here is the start:
+The first step is to include the required libraries and define the HTML elements. You'll need:
+
+1. The MRZ Scanner library (via CDN or local reference)
+2. The [PDF.js library](https://github.com/mozilla/pdf.js) for PDF support
+
+Here's the basic HTML structure:
```html
@@ -35,7 +40,7 @@ The first step in making the sample is to define the script references and the H
Dynamsoft MRZ Scanner - Use File Input
-
+
@@ -64,9 +69,9 @@ The first step in making the sample is to define the script references and the H
```
-### Step 2: Setting up PDF.js
+### Step 2: Configuring PDF.js
-Now that the HTML and scripts have been set, it's time to set up the PDF.js library in order to support loading PDFs into your web app. Here is the code to do that:
+Configure the PDF.js library to enable PDF loading in your application:
```html
```
-### Step 3: Initializing the Dynamsoft MRZ Scanner
+### Step 3: Initializing the MRZ Scanner
-Now that we are working on the main script of the operation of the web application, one of the first things that we need to do is to initialize the MRZ Scanner which will be responsible for the MRZ reading functionality of the web app.
+Initialize the MRZ Scanner with custom configuration to handle static images and PDFs:
```js
// Initialize the Dynamsoft MRZ Scanner
@@ -104,11 +109,14 @@ const mrzscanner = new Dynamsoft.MRZScanner({
});
```
-It is important to pay attention to the new properties that have been introduced to the [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) interface. The first new property is `uploadAcceptedTypes` which sets the file format(s) that the MRZ Scanner will accept. In this sample, we set to accept any image type as well as PDF. The second property is the `uploadFileConverter` - which is needed to support PDF files as those need to be converted to images so that the MRZ Scanner can accept them as input.
+Note the new properties in [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig):
+
+- **`uploadAcceptedTypes`**: Specifies accepted file formats (images and PDFs in this example)
+- **`uploadFileConverter`**: Converts PDFs to images before processing, as the scanner requires image input
-### Step 4: Implementing the convertPDFToImage function
+### Step 4: Implementing the PDF Conversion Function
-In the previous step, we used a `convertPDFToImage` function in the `uploadFileConverter` property, but that function has not been implemented yet. Let's implement that now:
+Implement the `convertPDFToImage` function referenced in the previous step:
```js
// PDF to image conversion function
@@ -162,15 +170,18 @@ async function convertPDFToImage(file) {
```
> [!NOTE]
-> It is important to note that currently, this sample only accepts **single-page PDF** files. The above `convertPDFToImage` function can process only a single-page PDF file.
+> This sample supports **single-page PDFs only**. Multi-page PDFs require additional logic to process each page.
-In this function, any **single-page** PDF file that is accepted as input is converted to a Blob that has a `PNG` type. Now that the PDF has been converted to a an image type, it's ready to get fed to the MRZ Scanner to be read.
+This function converts a **single-page** PDF file to a PNG Blob, making it compatible with the MRZ Scanner.
### Step 5: Launching the MRZ Scanner
-Now that all of the core functions needed for loading the image or PDF have been implemented, it's time to connect all of these parts to the [`launch`]({{ site.api }}mrz-scanner.html#launch) method of the MRZ Scanner. One of the main changes in v2.1 of the MRZ Scanner is that the `launch` method can now be run with a file input.
+With the PDF conversion function in place, connect everything to the [`launch`]({{ site.api }}mrz-scanner.html#launch) method. Starting in v2.1, the `launch` method accepts a file input parameter.
-In the code below, there are two trigger functions, one for launching the MRZ Scanner with its normal camera UI (MRZScannerView) The following trigger functions demonstrate how to read the MRZ from a file when said file is uploaded, then we automatically run the `launch` command in order to read the MRZ from the file without needing to click "Start Scan".
+The code below shows two ways to trigger the scanner:
+
+1. **Camera UI**: Click the "Start Scan" button to launch the standard camera interface
+2. **File Upload**: Select a file to automatically process it without showing the camera UI
```js
document.getElementById("start-scan").onclick = async function () {
@@ -200,11 +211,13 @@ document.getElementById("initialFile").onchange = async function () {
```
> [!NOTE]
-> Please note the difference in how the launch command is run when using the default UI (which includes the camera) and how the launch command is run when trying to read from a static image/file. When using the default UI, it is run as `mrzScanner.launch({})`. When reading from a static image, it is run as `mrzScanner.launch()` or `mrzScanner.launch(file)`.
+> The `launch()` method behavior differs based on the parameter:
+> - **No parameter or empty object** (`launch()` or `launch({})`): Opens the camera UI
+> - **File parameter** (`launch(file)`): Processes the file directly without UI
### Step 6: Displaying the Result
-When the MRZ is read, the last step that we need to do is to display the result to the user. Here is the `displayResult` function
+Finally, display the scanned MRZ results to the user:
```js
function displayResult(result) {
@@ -246,8 +259,16 @@ function displayResult(result) {
## Conclusion
-Now that the code is all done, all you need to do is run the app either via npm or you can host the source files yourself and serve your web application via a HTTPS environment.
+You now have a complete implementation for scanning MRZs from static images and PDFs. To run the application:
+
+1. Serve the files via HTTPS (required for the license to work)
+2. Use a local development server like the Five Server extension for VS Code, or
+3. Deploy to your web server
+
+This approach is ideal when:
-With this app, you can read MRZs from static images and files without needing to use the MRZScannerView UI, therefore covering cases where a camera is not needed at all or cases where the images are obtained via a different source e.g. via a scanner and Dynamic Web TWAIN.
+- Camera access is not needed
+- Images come from external sources (scanners, document management systems, etc.)
+- You want programmatic control over the scanning process
-If you have any questions about this use case, please contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/).
\ No newline at end of file
+For questions or support, contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/).
\ No newline at end of file
diff --git a/guides/mrz-scanner.md b/guides/mrz-scanner.md
index bea6653..d765427 100644
--- a/guides/mrz-scanner.md
+++ b/guides/mrz-scanner.md
@@ -11,20 +11,20 @@ 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.
+This user guide demonstrates how to build a web application that scans and parses MRZ (Machine Readable Zone) documents using the MRZ Scanner JavaScript Edition SDK. You'll learn to implement a complete scanning workflow from initialization to result handling, with practical examples you can adapt for your own application.
## License
### Trial License
-When getting started with MRZ Scanner, we recommend getting your own 30-day trial license through the following modal:
+Get started with a free 30-day trial license:
{% 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.
+The trial license can be renewed twice via the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense/?product=mrz&utm_source=guide&package=js) (15 days each renewal), giving you 60 days total for development and evaluation. Contact the [Dynamsoft Support Team](https://www.dynamsoft.com/company/contact/) if you need additional time or have 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.
+> The **MRZ Scanner** license includes licenses for **Dynamsoft Label Recognizer**, **Dynamsoft Code Parser**, and **Dynamsoft Camera Enhancer**, as the MRZ Scanner is built on these three products.
### Full License
@@ -33,11 +33,11 @@ If you are fully satisfied with the solution and would like to move forward with
## Quick Start - Including the Library
> [!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.
+> Visit the [Introduction]({{ site.introduction }}index.html) page to learn about MRZ document formats, the MRZ Scanner architecture, and system requirements.
-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).
+This guide uses vanilla JavaScript to demonstrate the core concepts. The complete code is available 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.
+The first step is to include the SDK in your application. You can include the SDK using a precompiled script or build it from source.
@@ -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@3.0.4 -E
+ npm i dynamsoft-mrz-scanner@3.1.0 -E
# or
- yarn add dynamsoft-mrz-scanner@3.0.4 -E
+ yarn add dynamsoft-mrz-scanner@3.1.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
-
+
@@ -99,76 +99,74 @@ Below is the complete Hello World sample page that uses the precompiled script s
```
> [!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.
+> This is a simplified version of the Hello World file hosted on [GitHub](https://github.com/Dynamsoft/mrz-scanner-javascript/blob/main/samples/hello-world.html). The GitHub version includes additional UI enhancements, but they are not necessary to successfully launch the MRZ Scanner. Remember to replace `YOUR_LICENSE_KEY_HERE` with your own license key.
-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.
+To run the sample, create a new file called `hello-world.html`, copy the code above into it, and serve it from a web 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`.
+**For VS Code users**: The [Five Server extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server) provides a quick way to serve the project. Install the extension, open `hello-world.html`, and click "Go Live" in the bottom right corner. This serves 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.
+Alternatively, you can use other web servers like IIS or Apache.
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.
+While the pre-compiled script is the easiest way to get started, you can also build the MRZ Scanner SDK from source for in-depth customization.
-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 MRZ Scanner is built using three 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). Customizing the MRZ Scanner involves working with the foundational APIs 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.
+To build from source, you'll retrieve the source files from the official [GitHub repository](https://github.com/Dynamsoft/mrz-scanner-javascript), compile them into a distributable package, and run the included Hello World sample.
-Follow these steps in order to build from the source:
+Follow these steps to build from 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).
+1. Download the source files from [GitHub](https://github.com/Dynamsoft/mrz-scanner-javascript) as a ZIP file (use the "Download ZIP" option).
-2. Extract the contents of the compressed folder.
+2. Extract the contents of the ZIP file.
-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).
+3. Open the Hello World sample at `/samples/hello-world.html` in your code editor.
-4. Search for 'YOUR_LICENSE_KEY_HERE' and replace that with your own license key, whether it is trial or full.
+4. Replace `YOUR_LICENSE_KEY_HERE` with your own license key.
-5. Install project dependencies - in the terminal, navigate to the project root directory and run the following:
+5. Install project dependencies by navigating to the project root directory and running:
```bash
npm install
```
-6. Build the project - once the dependencies are installed, build the project by running:
+6. Build the project:
```bash
npm run build
```
-7. Serve the project via `localhost`:
+7. Serve the project:
```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`.
+
+Once the server is running, open your browser and navigate to the address shown in the terminal output.
Self-hosting the Library Resources
-If you are looking to have a **completely offline setup**, we also provide the option to download the library's resource files, and then configuring them into your own server so that the users of your application would only need to connect to your server.
+For a **completely offline setup**, you can download the library resource files and host them on your own server, eliminating the need for external CDN dependencies.
### Acquiring the Resource Files
-The first step is to get a copy of the resources. There are two ways which you can do this:
+There are two ways to obtain the library resources:
-- 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.
+- **From GitHub**: Download the [GitHub repository](https://github.com/Dynamsoft/mrz-scanner-javascript) as a ZIP file. The library resources are in the `dist` folder—simply copy this folder to your project.
-- 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.4 -E`. Find the `dynamsoft-mrz-scanner` folder in `node_modules` and the *dist* folder will be inside.
+- **From npm**: Install the package with `npm i dynamsoft-mrz-scanner@3.1.0 -E`, then locate the `dist` folder inside `node_modules/dynamsoft-mrz-scanner`.
### Modify the Build Script
-Depending on the framework that is being used to develop the application, there are different ways to copy over the resources locally during the build process so that it is accessible to the app when it is deployed on a development or production server. Let's look at each of the supported frameworks:
+Each framework has a different approach for copying resources locally during the build process. Below are configurations for Angular, React, and Vue:
#### Angular
-For Angular, the main modification will happen in the **angular.json** file - specifically in the *assets* section of the file. The objective is to copy over the resources from the *node_modules* folder into the *dist/my-app/browser/assets* folder of the Angular project.
+Modify the `assets` section in **angular.json** to copy resources from `node_modules` to the `dist/my-app/browser/assets` folder:
```json
"assets": [
@@ -179,53 +177,51 @@ For Angular, the main modification will happen in the **angular.json** file - sp
{
"glob": "**/*",
"input": "node_modules/dynamsoft-mrz-scanner/dist",
- "output": "/assets/dynamsoft-mrz-scanner@3.0.4/dist"
+ "output": "/assets/dynamsoft-mrz-scanner@3.1.0/dist"
},
{
"glob": "**/*",
"input": "node_modules/dynamsoft-capture-vision-bundle/dist",
- "output": "/assets/dynamsoft-capture-vision-bundle@3.0.6001/dist"
+ "output": "/assets/dynamsoft-capture-vision-bundle@3.2.5000/dist"
},
{
"glob": "char-resources/**/*",
"input": "node_modules/dynamsoft-capture-vision-data",
- "output": "/assets/dynamsoft-capture-vision-data@1.0.1"
+ "output": "/assets/dynamsoft-capture-vision-data@1.1.0"
},
{
"glob": "models/**/*",
"input": "node_modules/dynamsoft-capture-vision-data",
- "output": "/assets/dynamsoft-capture-vision-data@1.0.1"
+ "output": "/assets/dynamsoft-capture-vision-data@1.1.0"
},
{
"glob": "parser-resources/**/*",
"input": "node_modules/dynamsoft-capture-vision-data",
- "output": "/assets/dynamsoft-capture-vision-data@1.0.1"
+ "output": "/assets/dynamsoft-capture-vision-data@1.1.0"
},
{
"glob": "templates/**/*",
"input": "node_modules/dynamsoft-capture-vision-data",
- "output": "/assets/dynamsoft-capture-vision-data@1.0.1"
+ "output": "/assets/dynamsoft-capture-vision-data@1.1.0"
},
{
"glob": "ui/**/*",
"input": "node_modules/dynamsoft-capture-vision-data",
- "output": "/assets/dynamsoft-capture-vision-data@1.0.1"
+ "output": "/assets/dynamsoft-capture-vision-data@1.1.0"
}
],
```
> [!NOTE]
-> The above script assumes that the `dynamsoft-mrz-scanner`, `dynamsoft-capture-vision-bundle`, and `dynamsoft-capture-vision-data` have all been installed via npm and are in the node_modules folder.
->
-> Furthermore, please note the version number that is at the end of the folder name above depends on the version of the library that is being used. This current script is based on the latest version of the library, v3.0.4.
+> Ensure that `dynamsoft-mrz-scanner`, `dynamsoft-capture-vision-bundle`, and `dynamsoft-capture-vision-data` are installed via npm. The version numbers in the folder names (e.g., `@3.1.0`) should match your installed library versions.
#### React
-In the React implementation, the script of **package.json** needs to be modified to get the resources to copy into the *public* folder. Here is what to add to the *scripts* section of the file:
+Modify the `scripts` section in **package.json** to copy resources into the `public` folder:
```json
"scripts": {
- "copy-resources": "mkdir -p public/libs && cp -r node_modules/dynamsoft-mrz-scanner/ public/libs/dynamsoft-mrz-scanner@3.0.4/ && cp -r node_modules/dynamsoft-capture-vision-bundle/ public/libs/dynamsoft-capture-vision-bundle@3.0.6001/ && cp -r node_modules/dynamsoft-capture-vision-data public/libs/dynamsoft-capture-vision-data@1.0.1",
+ "copy-resources": "mkdir -p public/libs && cp -r node_modules/dynamsoft-mrz-scanner/ public/libs/dynamsoft-mrz-scanner@3.1.0/ && cp -r node_modules/dynamsoft-capture-vision-bundle/ public/libs/dynamsoft-capture-vision-bundle@3.2.5000/ && cp -r node_modules/dynamsoft-capture-vision-data public/libs/dynamsoft-capture-vision-data@1.1.0",
"start": "react-scripts start",
"build": "npm run copy-resources && react-scripts build",
"test": "react-scripts test",
@@ -234,20 +230,17 @@ In the React implementation, the script of **package.json** needs to be modified
```
> [!NOTE]
-> The one new thing that was added is the `copy-resources` script which copies the resources needed from the *node_modules* folder into the *public/libs* folder so that it is accessible at runtime by the app. The `build` script was modified so that it runs `copy-resources` whenever it is called.
->
-> Please note that the version numbers in the copy-resources command is based on the latest version of dynamsoft-mrz-scanner, v3.0.4.
-
+> The `copy-resources` script copies resources from `node_modules` to `public/libs` for runtime access. The `build` script runs `copy-resources` automatically. Version numbers should match your installed library versions.
-Afterwards, running `npm build` on the root directory of the React project will copy over the resources.
+Run `npm run build` to copy the resources and build your project.
#### Vue
-Similar to the React implementation, the *scripts* of **package.json** needs to be modified to get the resources to copy into the *public* folder.
+Similar to React, modify the `scripts` section in **package.json**:
```json
"scripts": {
- "copy-resources": "mkdir -p public/libs && cp -r node_modules/dynamsoft-mrz-scanner/ public/libs/dynamsoft-mrz-scanner@3.0.4/ && cp -r node_modules/dynamsoft-capture-vision-bundle/ public/libs/dynamsoft-capture-vision-bundle@3.0.6001/ && cp -r node_modules/dynamsoft-capture-vision-data public/libs/dynamsoft-capture-vision-data@1.0.1",
+ "copy-resources": "mkdir -p public/libs && cp -r node_modules/dynamsoft-mrz-scanner/ public/libs/dynamsoft-mrz-scanner@3.1.0/ && cp -r node_modules/dynamsoft-capture-vision-bundle/ public/libs/dynamsoft-capture-vision-bundle@3.2.5000/ && cp -r node_modules/dynamsoft-capture-vision-data public/libs/dynamsoft-capture-vision-data@1.1.0",
"serve": "vue-cli-service serve",
"build": "npm run copy-resources && vue-cli-service build",
"lint": "vue-cli-service lint"
@@ -255,13 +248,11 @@ Similar to the React implementation, the *scripts* of **package.json** needs to
```
> [!NOTE]
-> The one new thing that was added is the `copy-resources` script which copies the resources needed from the *node_modules* folder into the *public/libs* folder so that it is accessible at runtime by the app. The `build` script was modified so that it runs `copy-resources` whenever it is called.
->
-> Please note that the version numbers in the copy-resources command is based on the latest version of dynamsoft-mrz-scanner, v3.0.4.
+> The `copy-resources` script copies resources from `node_modules` to `public/libs` for runtime access. The `build` script runs `copy-resources` automatically. Version numbers should match your installed library versions.
### Update the Engine Resource Paths
-By default, the engine resource paths of the libraries are usually set to the CDN links for each library. Once you modify the build script, the library resource files are then available locally so the engine resource paths can now be set to the path defined in the previous step.
+After copying the resources locally, update the MRZ Scanner configuration to point to your self-hosted files instead of the CDN:
#### React / Vue
@@ -269,9 +260,9 @@ By default, the engine resource paths of the libraries are usually set to the CD
const mrzScanner = new Dynamsoft.MRZScanner({
license: "YOUR_LICENSE_KEY_HERE",
scannerViewConfig: {
- uiPath: "/libs/dynamsoft-mrz-scanner@3.0.4/dist/mrz-scanner.ui.html",
+ uiPath: "/libs/dynamsoft-mrz-scanner@3.1.0/dist/mrz-scanner.ui.html",
},
- templateFilePath: "/libs/dynamsoft-mrz-scanner@3.0.4/dist/mrz-scanner.template.json",
+ templateFilePath: "/libs/dynamsoft-mrz-scanner@3.1.0/dist/mrz-scanner.template.json",
engineResourcePaths: {
rootDirectory: "/libs/"
}
@@ -287,9 +278,9 @@ const mrzScanner = new Dynamsoft.MRZScanner({
const config = {
license: 'YOUR_LICENSE_KEY_HERE', // Replace with your Dynamsoft license key
scannerViewConfig: {
- uiPath: "/assets/dynamsoft-mrz-scanner@3.0.4/dist/mrz-scanner.ui.html",
+ uiPath: "/assets/dynamsoft-mrz-scanner@3.1.0/dist/mrz-scanner.ui.html",
},
- templateFilePath: "/assets/dynamsoft-mrz-scanner@3.0.4/dist/mrz-scanner.template.json",
+ templateFilePath: "/assets/dynamsoft-mrz-scanner@3.1.0/dist/mrz-scanner.template.json",
engineResourcePaths: {
rootDirectory: "/assets/"
}
@@ -298,39 +289,38 @@ const config = {
### Server Requirements for Deployment
-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:
+When deploying your self-hosted resources, ensure your server meets these requirements:
+
+#### Secure Context (HTTPS Deployment)
+
+Serve your application via a secure HTTPS connection for production. This is required because:
-#### Secure context (HTTPS deployment)
+- **Camera Access**: Browsers only grant access to the camera video stream in a secure context.
+- **License Validation**: The Dynamsoft License requires a secure context to function.
-When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons
+> [!NOTE]
+> For development, some browsers (like Chrome) allow camera access on `http://127.0.0.1`, `http://localhost`, or `file:///` URLs.
-- 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.
+#### Set MIME Type for `.wasm` Files
-- 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:
+Configure your server to send the correct `Content-Type: application/wasm` header for WebAssembly files. Configuration varies by server:
- + Apache
- + IIS
- + NGINX
+- [Apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings)
+- [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap)
+- [NGINX](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types)
-## Breaking down Hello World
+## Understanding the Code
-Let's now go through the code of the Hello World sample to understand how the code works in detail.
+This section breaks down the Hello World sample to explain how each part works.
> [!NOTE]
-> If you are using a framework like React/Angular/Vue, please refer to the [framework samples]({{ site.codegallery }}index.html#frameworks) built by the development team.
+> For framework-specific implementations (React, Angular, Vue), refer to the [framework samples]({{ site.codegallery }}index.html#frameworks).
-### Step 1: Setting up the HTML and Including the MRZ Scanner
+### Step 1: Setting Up the HTML and Including the SDK
```html
@@ -339,7 +329,7 @@ Let's now go through the code of the Hello World sample to understand how the co
Dynamsoft MRZ Scanner - Hello World
-
+
@@ -349,9 +339,9 @@ 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---including-the-library) section) In this example, we include the precompiled MRZ Scanner SDK script via CDN in the header:
+The first step is to include the SDK in your HTML. As covered in the [Quick Start](#quick-start---including-the-library) section, this example uses the precompiled script from the jsDelivr CDN.
-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**.
+The MRZ Scanner includes a **Ready-to-Use UI** that automatically displays in a full-screen container when launched.
### Step 2: Initializing the MRZ Scanner
@@ -368,7 +358,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.
+This is the simplest way to initialize the [**`MRZScanner`**]({{ site.api }}mrz-scanner.html#mrzscanner). The configuration object sets the behavior of the scanner instance. The only **required** property is the **license key**—without a valid license, the scanner will display an error and fail to launch. Refer to the [License](#license) section for instructions on obtaining a license key.
### Step 3: Launching the MRZ Scanner
@@ -386,59 +376,81 @@ 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.html#mrzscanner) has been initialized, it's ready to launch. When `launch()` is called, this method:
+- Opens the MRZ Scanner UI in a full screen container.
+- Returns a Promise that resolves with the scanned [**`MRZResult`**](../api/mrz-scanner.md#mrzresult).
+- Presents the user with a two-stage scanning workflow.
+
+#### Scanning Workflow
+
+When launched, the scanner guides the users through two main stages:
+
+1. **Scanning Stage**: The `MRZScannerView` displays a camera interface for capturing MRZ documents.
+2. **Review Stage**: The `MRZResultView` shows the scanned image and parsed data for user verification.
-#### `MRZScannerView`
+Let's explore each view in detail:
-The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig), which is composed of the following UI elements:
+***MRZScannerView***
-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.
+The `MRZScannerView` is configured using [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig) and consists of these UI elements:
-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.
+**Core Scanning Interface:**
+
+1. **Camera View**: The camera viewfinder UI component that occupies the majority of the space, giving users a clear view and precise control of the image being scanned.
+
+2. **Scan Guide Frame**: An overlay that guides users to position the MRZ document correctly for fast and accurate scanning. Enabled **by default**, and can be hidden via [**`MRZScannerViewConfig`**]({{ site.api }}mrz-scanner.html#mrzscannerviewconfig). When enabled, the scanner crops the region outside the guide frame.
