Introduction

In an increasingly digital world where identity verification plays a critical role across industries such as banking, retail, travel, and law enforcement, being able to extract information from a driver's license quickly and accurately is more important than ever. Driver's licenses are one of the most commonly used forms of ID, and automating the process of reading them can save time, reduce errors, and streamline onboarding or check-in processes.

With the Dynamsoft Driver License Scanner (DDLS) JavaScript Edition, developers can easily integrate driver license scanning capabilities directly into their web applications using just a few lines of code. DDLS extracts key data such as name, address, date of birth, and license number, converting physical documents into structured, readable digital information in real time.

Whether you are building a customer portal, a check-in kiosk, or a mobile-first identity verification solution, DDLS JavaScript Edition offers powerful performance, flexibility, and ease of use to help you create seamless and secure user experiences.

Key Features

Document Detection and Optimization

• Automatically detects driver license boundaries in camera view
• Optimizes image quality for enhanced data extraction accuracy
• Real-time feedback for proper document positioning

PDF417 Barcode Decoding and Parsing

• Decodes PDF417 barcodes with high accuracy and error correction
• Parses encoded data into structured, human-readable information
• Supports all major driver license barcode standards

Multi-Format Support

• Handles various driver license layouts and designs
• Compatible with different jurisdictional formats
• Flexible scanning modes for different use cases

Ready-to-Use Interface

• Pre-built UI components for immediate integration
• Intuitive user experience with minimal configuration
• Responsive design for web and mobile applications

Supported Driver License Standards

The Dynamsoft Driver License Scanner (DDLS) JavaScript Edition supports multiple driver license standards for comprehensive coverage across different regions:

North America (AAMVA Standards)

The AAMVA DL/ID Card Design Standard specified by the American Association of Motor Vehicle Administrators (AAMVA) defines how to encode machine-readable information in PDF417 barcodes and magnetic stripes.

DDLS supports all versions of the AAMVA DL/ID specification:

• Versions: 2000, 2003, 2005, 2009, 2010, 2011, 2012, 2013, 2016
• Code Types:
  • AAMVA_DL_ID - Standard PDF417 barcode format
  • AAMVA_DL_ID_WITH_MAG_STRIPE - Combined PDF417 and magnetic stripe data

South Africa

Support for South African driver's licenses with personal information extraction:

• Code Type: SOUTH_AFRICA_DL
• Note: Currently supports essential personal information fields, with full information parsing planned for future releases

Design Principles

The DDLS JavaScript Edition is built around three fundamental design principles that prioritize developer efficiency and user experience:

1. Minimal Code Implementation - Our high-level API delivers complete recognition and parsing functionality in just a few lines of code, dramatically reducing both development time and ongoing maintenance overhead.

2. Ready-to-Deploy UI Components - Pre-built interface components and thoughtfully designed layouts eliminate the need for custom UI development, allowing developers to integrate scanning functionality immediately without additional design work.

3. Streamlined Customization - Intuitive configuration options provide flexible control over scanner behavior and performance settings, making it simple to adapt the solution to specific requirements without complexity.

User Guide for the Driver License 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.

System Requirements

Secure Context (HTTPS Deployment)

When deploying your web application for production, ensure it is served over a secure HTTPS connection. This is required for the following reasons:

1. Browser Security Restrictions – Most browsers only allow access to camera video streams in a secure context.

   Some browsers like Chrome may grant access to camera video streams for http://127.0.0.1, http://localhost, or even pages opened directly from the local file system (file:///...). This can be helpful during development and testing.

2. Dynamsoft License Requirements – A secure context is required for Dynamsoft licenses to function properly.

Required Browser Features

The following** browser features** are required for the DCE, DBR, DCP and DDN components:

1. WebAssembly
2. Blob
3. URL/createObjectURL
4. Web Workers

Supported Browsers

The table below lists the minimum supported versions of browsers based on these requirements:

Browser	Version
Chrome	v78+
Firefox	v79+
Safari	v15+
Edge	v92+

¹ iOS 14.3+ is required for camera video streaming in Chrome and Firefox or Apps using webviews.

License

Trial License

When you are getting started with the Driver License 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 Driver License Scanner license contains a license for Dynamsoft Document Normalizer, and Dynamsoft Camera Enhancer as those are the functional products that are central to the operation of the Driver License 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 - Building and Running Hello World

The purpose of this guide is to help you implement a Hello World application using the Driver License Scanner solution. To showcase this, we will be using vanilla JS with the source code in this repository.

Building the Library from Source

This method uses the Driver License Scanner for Web source files in this repository, compiles them into a distributable package, and then runs the ready-made Hello World sample page.

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

1. Clone or download this repository

2. Open the Hello World sample included with the source files located at samples/hello-world/index.html

3. Replace 'YOUR_LICENSE_KEY_HERE' with your own license key, whether it is trial or full.

4. Install project dependencies - in the terminal, navigate to the project root directory and run the following:

   npm install

5. Build the project - once the dependencies are installed, build the project by running:

   npm run build

6. Serve the project via localhost:

   npm run serve

   Once the server is running, the application will be available at https://localhost:3001/. Open this address in your browser to access the Hello World sample.

Scanning Workflow

The Driver License Scanner consists of three main view components that work together to provide a complete scanning experience:

• DriverLicenseScannerView - The primary scanning interface responsible for camera operations and license capture
• DriverLicenseVerifyView - The verification interface that allows users to review and confirm captured images
• DriverLicenseResultView - The results interface that displays extracted data and final processed images

By default, the scanning process follows a structured workflow through these five stages:

1. Front License Scan - Capture the front side of the driver license
2. Front License Verify - Review and confirm the captured front image
3. Back License Scan - Capture the back side of the driver license
4. Back License Verify - Review and confirm the captured back image
5. Result View - Display extracted data and final images

Using the Built Library

After building the project, you can include the SDK using the generated bundle file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Dynamsoft Driver License Scanner - Hello World</title>
    <script src="../dist/ddls.bundle.js"></script>
  </head>

  <body>
    <h1 style="font-size: large">Dynamsoft Driver License Scanner</h1>
    <div id="results"></div>

    <script>
      const resultContainer = document.querySelector("#results");

      // Initialize the Dynamsoft Driver License Scanner
      const driverLicenseScanner = new Dynamsoft.DriverLicenseScanner({
        license: "YOUR_LICENSE_KEY_HERE",
        scannerViewConfig: {
          uiPath: "../../dist/ddls.ui.html",
        },
        templateFilePath: "../../dist/ddls.template.json",
        /* Set `engineResourcePaths` if you're self-hosting for offline support */
        // engineResourcePaths: {
        //   dcvBundle: "../../resources/dynamsoft-capture-vision-bundle/dist/",
        //   dcvData: "../../resources/dynamsoft-capture-vision-data/",
        // },
      });
      (async () => {
        // Launch the scanner and wait for the result
        const result = await driverLicenseScanner.launch();
        console.log(result);

        resultContainer.innerHTML = ""; // Clear placeholder content

        // Clear the result container and display the scanned result as a canvas
        Object.values(result).forEach((side) => {
          if (side?.deskewedImageResult) {
            const canvas = side.deskewedImageResult.toCanvas();
            resultContainer.appendChild(canvas);
          } else {
            resultContainer.innerHTML = "<p>No image scanned. Please try again.</p>";
          }
        });

        // Clear the result container and display the scanned result
        if (result?.licenseData?.status.code === Dynamsoft.EnumResultStatus.RS_SUCCESS) {
          Object.entries(result?.licenseData).map(([key, val]) => {
            const div = document.createElement("div");
            div.innerHTML = `<p>${key}: ${JSON.stringify(val)}</p>`;
            resultContainer.append(div);
          });
        } else {
          resultContainer.innerHTML = "<p>No data scanned. Please try again.</p>";
        }
      })();
    </script>
  </body>
</html>

Note

Please do not forget to replace YOUR_LICENSE_KEY_HERE with your own license key, whether it is trial or full.

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 Driver License Scanner

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Dynamsoft Driver License Scanner - Hello World</title>
    <script src="../../dist/ddls.bundle.js"></script>
  </head>

  <body>
    <h1 style="font-size: large">Dynamsoft Driver License Scanner</h1>
    <div id="results"></div>
  </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 Driver License 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 Driver License Scanner comes with a Ready-to-Use UI, it is not necessary to place complex UI elements. Once the scanner is launched, the Ready-to-Use UI will come up and occupy the page.

The main DOM element that is required in the <body> is a <div> element where the scan results will be displayed once the scanning workflow is complete.

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

Step 2: Initialize the Driver License Scanner

// Initialize the Dynamsoft Driver License Scanner
const driverLicenseScanner = new Dynamsoft.DriverLicenseScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  scannerViewConfig: {
    uiPath: "../../dist/ddls.ui.html",
  },
  templateFilePath: "../../dist/ddls.template.json",
  /* Set `engineResourcePaths` if you're self-hosting for offline support */
  // engineResourcePaths: {
  //   dcvBundle: "../../resources/dynamsoft-capture-vision-bundle/dist/",
  //   dcvData: "../../resources/dynamsoft-capture-vision-data/",
  // },
});

Above you will see the simplest way that you can initialize the Driver License Scanner. The one that is absolutely required in this setup is the license. Without a valid license, the Driver License 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.

Since the npm package has not been released yet, the following additional configuration properties are required to properly locate the necessary files:

uiPath - The file path to the custom UI HTML file that defines the scanner interface components.

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.

engineResourcePaths - The engine files of the library make up the core of the library and define the operation. 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.

Note

Once the npm package is officially released, these path configurations will be simplified as the package manager will handle file location automatically.

Step 3: Launching the Driver License Scanner

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

  resultContainer.innerHTML = ""; // Clear placeholder content

  // Clear the result container and display the scanned result as a canvas
  Object.values(result).forEach((side) => {
    if (side?.deskewedImageResult) {
      const canvas = side.deskewedImageResult.toCanvas();
      resultContainer.appendChild(canvas);
    } else {
      resultContainer.innerHTML = "<p>No image scanned. Please try again.</p>";
    }
  });

  // Clear the result container and display the scanned result
  if (result?.licenseData?.status.code === Dynamsoft.EnumResultStatus.RS_SUCCESS) {
    Object.entries(result?.licenseData).map(([key, val]) => {
      const div = document.createElement("div");
      div.innerHTML = `<p>${key}: ${JSON.stringify(val)}</p>`;
      resultContainer.append(div);
    });
  } else {
    resultContainer.innerHTML = "<p>No data scanned. Please try again.</p>";
  }
})();

Now that the Driver License Scanner has been initialized and configured, it is ready to be launched! The scanning workflow involves multiple steps:

1. Front Side Scanning (by default)
2. Back Side Scanning (by default)
3. Barcode Reading (from back side by default)
4. Data Extraction and Display

Once scanning is complete, the results are displayed as canvas images in the results container.

Understanding the Results

The result object contains the following structure:

• frontSide: Front side image and extracted data
• backSide: Back side image and barcode data
• licenseData: Parsed license information (name, address, expiry date, etc.)

Each side object may contain:

• deskewedImageResult: The captured image that can be converted to canvas
• Extracted text data from that side of the license

Common Issues

Camera not working?

• Ensure you're serving over HTTPS (required for camera access in production)
• Check browser permissions for camera access
• Verify your browser version meets the minimum requirements

License errors?

• Verify your license key is correctly copied (no extra spaces or characters)
• Check if your trial license has expired
• Ensure you're using the correct license type for your environment
• Need more help? Contact the Dynamsoft Support Team for license-related issues

Build or serve issues?

• Ensure Node.js is installed and up to date
• Try deleting node_modules and running npm install again
• Check that port 3001 is available on your system

Note

In the Hello World sample, the results are simply displayed as canvas images. For more advanced workflows, including barcode-only scanning, data extraction, and custom UI configurations, please refer to the guides below.

Next Steps

Now that you got the most basic functionality of the Driver License Scanner up and running, it's time to explore the many ways in which the Driver License Scanner can be used, including customization and specialized workflows. To learn more about these topics, please visit the following guide:

• Customizing the Driver License Scanner
• Complete API Reference

Support

For questions or issues with the Driver License Scanner, please contact the Dynamsoft Support Team.