MRZ Scanner JavaScript Edition API Reference

new MRZScanner(config: MRZScannerConfig)

const mrzScanner = new Dynamsoft.MRZScanner({
    license: "YOUR_LICENSE_KEY_HERE",
    scannerViewConfig: {
        // For custom scanning configuration, MRZScannerViewConfig goes in here
    },
    resultViewConfig: {
        // For custom result configuration, MRZResultViewConfig goes in here
    }
});

launch(): Promise<MRZResult>

launch(fileToProcess): Promise<MRZResult>

(async () => {
    // Launch the scanner and wait for the result
    try {
        const result = await mrzScanner.launch();
        console.log(result); // print the MRZResult to the console
    } catch (error){
        console.error(error);
    }
})();

(async () => {
    // Launch the scanner and wait for the result
    try {
        const result = await mrzScanner.launch(fileToProcess);
        console.log(result); // print the MRZResult to the console
    } catch (error){
        console.error("Error processing file:", error);
    }
})();

dispose(): void

mrzScanner.dispose();
console.log("Scanner resources released.");

interface MRZScannerConfig {
  license?: string; // license is absolutely required to be set at initialization
  container?: HTMLElement | string; //

  // Resource/Template specific configuration
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  engineResourcePaths?: EngineResourcePaths;

  // Views Configuration
  scannerViewConfig?: Omit<MRZScannerViewConfig, "templateFilePath" | "utilizedTemplateNames">;
  resultViewConfig?: MRZResultViewConfig;

  mrzFormatType?: Array<EnumMRZDocumentType>;
  showResultView?: boolean;
}

const mrzConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    mrzFormatType: ["passport", "td1"], // set the MRTD formats to just passport and ID (TD1)
    showResultView: false, // hide the final MRZResultView and go back to landing page once the MRZ result is in
    // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference
    engineResourcePaths: {
        std: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-std/dist/",
        dip: "https://cdn.jsdelivr.net/npm/dynamsoft-image-processing/dist/",
        core: "https://cdn.jsdelivr.net/npm/dynamsoft-core/dist/",
        license: "https://cdn.jsdelivr.net/npm/dynamsoft-license/dist/",
        cvr: "https://cdn.jsdelivr.net/npm/dynamsoft-capture-vision-router/dist/",
        dlr: "https://cdn.jsdelivr.net/npm/dynamsoft-label-recognizer/dist/",
        dcp: "https://cdn.jsdelivr.net/npm/dynamsoft-code-parser/dist/",
    },
    scannerViewConfig: {
        // the MRZScannerViewConfig goes in here - see MRZScannerViewConfig section
    },
    resultViewConfig: {
        // the MRZResultViewConfig goes in here - see MRZResultViewConfig section
    }
};

// Initialize the Dynamsoft MRZ Scanner with the above MRZScannerConfig object
const mrzScanner = new Dynamsoft.MRZScanner(mrzConfig);

interface MRZScannerViewConfig {
  uiPath?: string;
  container?: HTMLElement | string;

  showScanGuide?: boolean;
  showUploadImage?: boolean;
  showFormatSelector?: boolean;
  showSoundToggle?: boolean;
  showPoweredByDynamsoft?: boolean;

  enableMultiFrameCrossFilter?: boolean; // false by default

  uploadAcceptedTypes?: string;
  uploadFileConverter?: (file: File) => Promise<Blob>;
}

const mrzScanViewConfig = {
    showScanGuide: true, // hides the scan guide frame; true by default
    showUploadImage: true, // hides the load image icon that shows up in the toolbar at the top of the view; true by default
    showFormatSelector: true, // hides the format selector box if more than two MRZ types are assigned; true by default
    showSoundToggle: false, // hides the sound icon that allows the user to control whether a beep is played once an MRZ is recognized; true by default
    showPoweredByDynamsoft: false; // hides the "Powered By Dynamsoft" message that appears on the scanner UI; true by default
    enableMultiFrameCrossFilter: true, // turning the filter off could improve the speed but at the cost of result accuracy; true by default

    uploadAcceptedTypes: "image/*,application/pdf", // allows the user to upload static images and PDFs to be read by the MRZ Scanner - default is "image/*"
    uploadFileConverter: async (file) => {
        if (file.type === "application/pdf") {
            // Example PDF to image conversion
            const pdfData = await convertPDFToImage(file);
            return pdfData;
        }

        // For other non-image types, you can add more conversion logic
        // If it's not a supported type, throw an error
        throw new Error("Unsupported file type");
    },
};

const mrzConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    scannerViewConfig: mrzScanViewConfig
};

interface MRZResultViewConfig {
  container?: HTMLElement | string;
  toolbarButtonsConfig?: MRZResultViewToolbarButtonsConfig;
  showOriginalImage?: boolean;
  allowResultEditing?: boolean; // New option to control if result fields can be edited
  showMRZText?: boolean;
  emptyResultMessage?: string;

  onDone?: (result: MRZResult) => Promise<void>;
  onCancel?: (result: MRZResult) => Promise<void>;
}

const mrzResultViewConfig = {
    showOriginalImage: false, // Hides the cropped image of the MRZ document in the result view; true by default
    allowResultEditing: true, // Allows the user to manually edit the text of the parsed result fields; false by default
    showMRZText: false, // Hides the raw MRZ text as a field in the result view; true by default
    emptyResultMessage: "No MRZ is detected. Please try again.", // Change the message if there is no MRZ is detected. The default message is "The necessary information couldn't be detected. Please try again."
    toolbarButtonsConfig: {
        retake: {
            label: "Re-scan", // Changes the text label of the retake button to "Re-scan"; string is "Re-take" by default
            isHidden: true // Hides the retake button; false by default
        },
        done: {
            label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default
            isHidden: false // Hides the done button; false by default
        },
        cancel: {
            label: "Try Again", // Changes the text label of the cancel button; string is "Cancel" by default
            isHidden: false // Hides the cancel button; false by default.
        }
    },
    /* onDone is a callback that allows you to define the action(s) to take once the user clicks the Done button and the scanner is closed. By default, nothing happens and the app goes back to the landing page. */
    onDone: (result) => {
        console.log(result.status.message);
        console.log(result.data.firstName);
    },
    /* onCancel is a callback that allows you to define the action(s) that will happen once the user clicks the Cancel button which only shows up if the MRZ scanner is launched with a static file rather than with the camera view. By default, nothing happens and the app goes back to the landing page */
    onCancel: (result) => {
        /* implement the code to redirect the user to a new page should you not want them to go back to the landing page since that is the default behaviour */
    }
};

const mrzConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    resultViewConfig: mrzResultViewConfig
};

interface MRZResultViewToolbarButtonsConfig {
  retake?: ToolbarButtonConfig;
  done?: ToolbarButtonConfig;
  cancel?: ToolbarButtonConfig;
}

const mrzButtonConfig = {
    retake: {
        label: "Re-scan",
        isHidden: false
    },
    done: {
        label: "Return Home",
        isHidden: false
    },
    cancel: {
        label: "Try Again",
        isHidden: false
    }
};

const mrzResultViewConfig = {
    toolbarButtonsConfig: mrzButtonConfig,
};

export interface ToolbarButtonConfig {
  icon: string;
  label: string;
  className?: string;
  isHidden?: boolean;
}

export interface MRZResult {
  status: ResultStatus;
  originalImageResult?: DSImageData;
  data?: MRZData;
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.status.message); // prints the result status message to the console
    console.log(result.status.code); // prints the result status code to the console
    console.log(result.data); // prints the entire MRZData object of the result to the console
})();

export interface MRZData {
  [EnumMRZData.InvalidFields]?: EnumMRZData[]; //invalidFields
  [EnumMRZData.DocumentType]: string; // documentType
  [EnumMRZData.DocumentNumber]: string; // documentNumber
  [EnumMRZData.MRZText]: string; // mrzText
  [EnumMRZData.FirstName]: string; // firstName
  [EnumMRZData.LastName]: string; // lastName
  [EnumMRZData.Age]: number; // age
  [EnumMRZData.Sex]: string; // sex
  [EnumMRZData.IssuingState]: string; // issuingState
  [EnumMRZData.IssuingStateRaw]: string; //issuingStateRaw
  [EnumMRZData.Nationality]: string; // nationality
  [EnumMRZData.NationalityRaw]: string; //nationalityRaw
  [EnumMRZData.DateOfBirth]: MRZDate; // dateOfBirth
  [EnumMRZData.DateOfExpiry]: MRZDate; // dateOfExpiry
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.data.firstName); // prints the first name
    console.log(result.data.lastName); // prints the last name
    console.log(result.data.sex); // prints the sex
    console.log(result.data.nationality); // prints the nationality
    console.log(result.data.documentNumber); // prints the MRZ document number
})();

interface MRZDate {
  year: number;
  month: number;
  day: number;
}

(async () => {
    // Launch the scanner and wait for the result
    const result = await mrzScanner.launch();
    console.log(result.data.dateOfBirth.year); // prints the year of the date of birth
    console.log(result.data.dateOfBirth.month); // prints the month of the date of birth
    console.log(result.data.dateOfBirth.day); // prints the day of the date of birth
})();

type ResultStatus = {
  code: EnumResultStatus;
  message?: string;
};