dynamsoft-mrz-scanner

v3.1.0

Published

7 days ago

Dynamsoft MRZ Scanner JavaScript Edition is a ready-to-use SDK for web applications that accurately recognizes and parses Machine-Readable Zones on Machine-Readable Travel Documents.

Downloads

715

0High
0Medium
0Low

dm_npm_publisher

document scanning js javascript dynamsoft passport mrz scanner ui camera vision

User Guide for the MRZ Scanner for Web

This user guide will walk you through the Hello World sample app. When creating your own application, we recommend using this sample as a reference.

To learn about what an MRZ is, along with the makeup and system requirements of this solution, please visit the MRZ Introduction page on the Dynamsoft website.

License

Trial License

When you are getting started with the MRZ Scanner solution, we recommend getting your own 30-day trial license through the customer portal. The trial license can be renewed via the same customer portal twice, each time for another 15 days, giving you a total of 60 days to develop your own application using the solution. If more time is needed for a full evaluation, please contact the Dynamsoft Support Team.

Note:
Please note that the MRZ Scanner license contains a license for the Dynamsoft Label Recognizer, Dynamsoft Code Parser, and the Dynamsoft Camera Enhancer as those are the three functional products that are central to the operation of the MRZ Scanner.

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.

Quick Start - Including the SDK and creating 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 Github repository.

The first step before you venture into writing the code is to include the SDK in your application. The simplest way to include the SDK would be to use the precompiled script - but you can also build it from source yourself.

Using the Precompiled Script

The simplest way to include the SDK is to use either the jsDelivr or UNPKG CDN. The Hello World sample that this guide will explore uses jsDelivr:

jsDelivr

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mrz-scanner.bundle.js"></script>

UNPKG

<script src="https://unpkg.com/[email protected]/dist/mrz-scanner.bundle.js"></script>

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:

npm i [email protected] -E
# or
yarn add [email protected] -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 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.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Dynamsoft MRZ Scanner - Hello World</title>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mrz-scanner.bundle.js"></script>
  </head>

  <body>
    <h1 style="font-size: large">Dynamsoft MRZ Scanner</h1>

    <script>
      // Initialize the Dynamsoft MRZ Scanner
      const mrzScanner = new Dynamsoft.MRZScanner({
        license: "YOUR_LICENSE_KEY_HERE",
      });
      (async () => {
        // Launch the scanner and wait for the result
        const result = await mrzScanner.launch();
      })();
    </script>
  </body>
</html>

[!NOTE]
This code is identical to the Hello World file mentioned in Build from Source, except for the script source.
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. 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.

Building the Library from Source

In this guide, we will show the developer how to build the scanner themselves from the source files. The advantage of doing this is that it allows the developer to do some deep customization of the scanner if they are familiar with using the foundational products Dynamsoft Label Recognizer, Dynamsoft Code Parser, and the Dynamsoft Camera Enhancer.

Please note that we also offer a pre-compiled script reference to make the inclusion of the library even easier. To learn how to use that, please visit the full User Guide for the MRZ Scanner.

This method requires retrieving the MRZ Scanner for Web source files from its Github repository, compiles them into a distributable package, and then runs a ready-made Hello World sample page that is already included in the repo.

Please follow these steps in order to build from the source:

Download the MRZ Scanner for Web source files from Github as a compressed folder ("Download ZIP" option).
Extract the contents of the compressed folder.
Open the Hello World sample included with the source files located at samples/hello-world.html
Search for 'YOUR_LICENSE_KEY_HERE' and replace that with your own license key, whether it is trial or full.
Install project dependencies - in the terminal, navigate to the project root directory and run the following:
```
npm install
```
Build the project - once the dependencies are installed, build the project by running:
```
npm run build
```
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 after running npm run serve.

Breaking down Hello World

Let's now go through the code of the Hello World sample and understand the purpose of each section and how they all work together to bring the app to life.

Step 1: Setting up the HTML and Including the MRZ Scanner

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Dynamsoft MRZ Scanner - Hello World</title>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/mrz-scanner.bundle.js"></script>
  </head>

  <body>
    <h1 style="font-size: large">Dynamsoft MRZ Scanner</h1>
  </body>
</html>

The first step in setting up the HTML in a Hello World implementation is to include the SDK. The ways to include the SDK has already been addressed in the Quick Start section, so please refer to that if you have not already. In this example, we are including the MRZ Scanner via the precompiled script as that is the easiest way to get started.

Since this is a Hello World implementation, the HTML body will be kept quite simple. Since the MRZ Scanner comes with a Ready-to-Use UI, it is not necessary to place any <div> placeholder elements or anything like. Once the scanner is launched, the Ready-to-Use UI will come up and occupy the page.

Now let's move to the main script that will define the operation of the MRZ scanning.

Step 2: Initialize the MRZ Scanner

// Initialize the Dynamsoft MRZ Scanner
const mrzscanner = new Dynamsoft.MRZScanner({
  license: "YOUR_LICENSE_KEY_HERE",
});

Above you will see the simplest way that you can initialize the MRZ Scanner. The one that is absolutely required in this setup is the license. Without a valid license, the MRZ Scanner view will not launch and you will be met with an error message explaining that the license key is invalid or has expired. To learn how to get your own license, please refer to the License section of the guide.

Step 3: Launching the MRZ Scanner

(async () => {
  // Launch the scanner and wait for the result
  const result = await mrzscanner.launch();
  console.log(result);
})();

Now that the MRZ Scanner has been initialized and configured, it is ready to be launched! Once the MRZ Scanner is launched, the user will see the main MRZScannerView. Once a MRZ is scanned (via video or static image), the MRZ Scanner then switches to the MRZResultView to display 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

Here is a quick breakdown of the UI elements that make up the main view of the MRZ Scanner

Camera View: The majority of the space of the MRZScannerView is occupied by the camera view to give the user a complete picture of what is being seen by the camera.
Scan Guide Frame: By default, at the centre of the camera view you will find a frame that helps guide the user on where to place the MRZ document to get a fast and accurate result. Please note that if scan guide frame is shown, then anything outside of the frame will not be captured. This frame can be hidden via the MRZScannerViewConfig interface.
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 interface, while the visibility of the format selector itself is configurable via the MRZScannerViewConfig interface. To learn about MRZ formats, please refer to the Introduction page.
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.
Load Image Button: When this button is clicked, the user can select a MRZ document image from the device's local storage to be recognized.
Sound Button: By toggling this on, the MRZ Scanner will play a beep sound to signal that the MRZ has been successfully recognized.
Flash Button: This button is responsible for toggling the flash of the camera should it have one. If the device doesn't have the flash feature or if the browser being used doesn't support flash, this flash icon will not show up.
Close Scanner Button: Clicking this button will close the MRZ Scanner and take the user back to the landing page.

MRZResultView

Here is a quick breakdown of the UI elements that make up the result view

Original Image: A cropped image of the MRZ document that was just scanned will be displayed at the top by default.
Parsed Results: The parsed results, along with their corresponding field names, are displayed in a form view underneath the original image. In addition to displaying these parsed results, the MRZ Scanner allows the user to edit any of the fields if they find that any of the parsed info is incorrect after cross referencing it with the info on the MRZ document.
Re-take Button: Clicking this button allows the user to go back to the MRZScannerView to scan another MRZ document.
Done Button: Clicking this button basically closes the scanner and destroys the MRZScanner instance. At that point, the application will go back to the landing page, but the developer can dictate the action to take once this button is clicked. These actions can include allowing the user to perform some extra actions with the MRZ result, or navigating to another page, or really anything that the developer would like to do once the scanning operation is done.

[!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