Scanbot SDK has been acquired by Apryse! Learn more

Learn more
Skip to content

How to build an Ionic Capacitor MRZ Scanner app

Kevin October 1, 2025 7 mins read
Ionic Capacitor Data Capture SDK

In this tutorial, we’ll use Capacitor with Ionic and Angular to build a cross-platform app for Android and iOS that extracts data from machine-readable zones on passports and other ID documents.

To implement the scanning functionalities, we’ll use the Scanbot MRZ Scanner SDK.

Scanning a machine-readable zone on a passport with our Ionic Capacitor MRZ Scanner app

Building our app involves the following steps:

  1. Preparing the project
  2. Installing the Scanbot SDK
  3. Initializing the SDK
  4. Implementing the scanning feature
Want to see the final code right away? Click here.

home.page.ts:

import { Component } from '@angular/core';
import {
  IonHeader,
  IonToolbar,
  IonTitle,
  IonContent,
  IonButton,
} from '@ionic/angular/standalone';

import { ScanbotSDK, MRZ } from 'capacitor-plugin-scanbot-sdk';
import {
  startMRZScanner,
  MrzScannerScreenConfiguration,
} from 'capacitor-plugin-scanbot-sdk/ui_v2';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonButton],
})
export class HomePage {
  constructor() {}

  async startScanner() {
    try {
      if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
        return;
      }

      const configuration = new MrzScannerScreenConfiguration();
      const result = await startMRZScanner(configuration);

      if (result.status === 'OK' && result.data.mrzDocument) {
        const mrz = new MRZ(result.data.mrzDocument);
        alert(
          'MRZ data:\n' +
            `Document type: ${mrz.documentType?.value?.text} \n` +
            `Given names: ${mrz.givenNames?.value?.text} \n` +
            `Surname: ${mrz.surname?.value?.text}\n` +
            `Date of birth: ${mrz.birthDate?.value?.text}\n` +
            `Document number: ${mrz.documentNumber?.value?.text}`
        );
      }
    } catch (e: any) {
      console.log(
        'An error has occurred while running the scanner',
        e.message
      );
    }
  }
}

Requirements

Before starting development with Capacitor, you need to set up your environment.

The prerequisites for developing Ionic Capacitor apps are:

Core requirements:

  • Node.js version 20.19 or higher

For iOS development:

  • iOS 14+
  • macOS with Xcode 16+
  • Xcode Command Line Tools
  • Homebrew
  • Cocoapods

For Android development:

  • Android Studio Jellyfish | 2024.2.1+
  • Android SDK (API Level 22+), Platforms and Developer Tools
  • Android Gradle Plugin 8.4.0+ or Kotlin Plugin applied

To get the full benefits and experience from using our SDK, we also recommend real devices for testing.

Developing Capacitor applications can be done via the CLI or using the VS Code extension. In this tutorial, we’ll use CLI commands. However, feel free to follow along using whatever option suits you best.

Capacitor can be used with different frameworks. In this tutorial, we will use Capacitor with Ionic and Angular. Again, these choices depend on your needs and prior knowledge.

Since we’ll use Ionic in this tutorial, you also need to install the Ionic CLI if you haven’t already:

npm install -g @ionic/cli

Step 1: Prepare the project

1. Create a new Capacitor project

To start creating your Capacitor app with Ionic using the CLI, run the following command in the terminal, which will create a blank project with some recommended Capacitor dependencies:

ionic start CapacitorTutorial blank --capacitor --type angular-standalone --package-id io.scanbot.tutorial.capacitor

⚠️ When using your own license, make sure that the package ID is the same as the application/bundle ID associated with it.

2. Generate the native projects

Now, let’s add the Android and iOS platforms to our project.

Navigate into the project directory.

cd CapacitorTutorial

Then add Android and iOS as platforms.

npm i @capacitor/android @capacitor/ios

And run the following commands to create the native Android and iOS projects:

npx cap add android
npx cap add ios

Step 2: Install the Scanbot SDK

To install the Scanbot SDK, run:

npm i capacitor-plugin-scanbot-sdk

💡 This will install the latest Scanbot SDK version. You can find more information about each version in the changelog.

Now that the npm package has been installed, we need to make some changes to the native projects.

For Android, we need to add the camera permission and feature in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />

For iOS, we need to include a description for the camera permission in ios/App/App/Info.plist anywhere inside the <dict> element:

<key>NSCameraUsageDescription</key>
<string>Grant camera permission to start scanning.</string>

Now that the project is set up, we can start integrating the scanning functionalities.

Step 3: Initialize the SDK

Before using any feature of the Scanbot SDK, we need to initialize it. Ideally, initialization should be done as soon as the app is launched.

In this tutorial, we’re going to initialize the SDK inside a ngOnInit callback in src/app/app.component.ts. Make sure to import OnInit and ScanbotSDK.

Your app.component.ts will look like this:

import { Component, OnInit } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

import { ScanbotSDK } from 'capacitor-plugin-scanbot-sdk';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  imports: [IonApp, IonRouterOutlet],
})
export class AppComponent implements OnInit {
  constructor() { }

  ngOnInit(): void {
    ScanbotSDK.initializeSDK({
      licenseKey: ""
    }).then(result => console.log(result))
      .catch(err => console.log(err));
  }  
}

💡 Without a license key, our SDK only runs for 60 seconds per session. This is more than enough for the purposes of our tutorial, but if you like, you can generate a license key using the bundle and application identifiers.

Step 4: Implement the scanning feature

In your project folder, go to src/app/home/home.page.html, and add a button inside the container div that will start the scanning process.

<ion-button (click)="startScanner()">Start MRZ Scanner</ion-button>

Next, define the startScanner function inside the HomePage class in src/app/home/home.page.ts. We’ll parse the raw data into a structured MRZ object and display the key information, such as the document type, name, and birth date, in an alert.

async startScanner() {
  try {
    /** Check license status and return early if the license is not valid */
    if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
      return;
    }
    /**
     * Create the configuration object and
     * start the scanner with the configuration
     */
    const configuration = new MrzScannerScreenConfiguration();
    const result = await startMRZScanner(configuration);
    /**
     * Handle the result if the result status is OK
     */
    if (result.status === 'OK' && result.data.mrzDocument) {
      const mrz = new MRZ(result.data.mrzDocument);
      alert(
        'MRZ data:\n' +
          `Document type: ${mrz.documentType?.value?.text} \n` +
          `Given names: ${mrz.givenNames?.value?.text} \n` +
          `Surname: ${mrz.surname?.value?.text}\n` +
          `Date of birth: ${mrz.birthDate?.value?.text}\n` +
          `Document number: ${mrz.documentNumber?.value?.text}`
      );
    }
  } catch (e: any) {
    console.log(
      'An error has occurred while running the scanner',
      e.message
    );
  }
}

Your final home.page.ts should look something like this:

import { Component } from '@angular/core';
import {
  IonHeader,
  IonToolbar,
  IonTitle,
  IonContent,
  IonButton,
} from '@ionic/angular/standalone';

import { ScanbotSDK, MRZ } from 'capacitor-plugin-scanbot-sdk';
import {
  startMRZScanner,
  MrzScannerScreenConfiguration,
} from 'capacitor-plugin-scanbot-sdk/ui_v2';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  imports: [IonHeader, IonToolbar, IonTitle, IonContent, IonButton],
})
export class HomePage {
  constructor() {}

  async startScanner() {
    try {
      if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
        return;
      }

      const configuration = new MrzScannerScreenConfiguration();
      const result = await startMRZScanner(configuration);

      if (result.status === 'OK' && result.data.mrzDocument) {
        const mrz = new MRZ(result.data.mrzDocument);
        alert(
          'MRZ data:\n' +
            `Document type: ${mrz.documentType?.value?.text} \n` +
            `Given names: ${mrz.givenNames?.value?.text} \n` +
            `Surname: ${mrz.surname?.value?.text}\n` +
            `Date of birth: ${mrz.birthDate?.value?.text}\n` +
            `Document number: ${mrz.documentNumber?.value?.text}`
        );
      }
    } catch (e: any) {
      console.log(
        'An error has occurred while running the scanner',
        e.message
      );
    }
  }
}

In the terminal, run these commands to build and sync the native projects:

npm run build
npx cap sync

To run the app on Android and iOS, use the following commands:

For Android:

npx cap run android

For iOS:

To run the app on a real iOS device, you need to adjust the “Provisioning” and “Signing” settings. Open ios/App/App.xcworkspace with Xcode, adjust the settings, and run the project from Xcode or with this command:

npx cap run ios
Scanning a machine-readable zone on a passport with our Ionic Capacitor MRZ Scanner app

Conclusion

And that’s it! You’ve successfully integrated a fully functional MRZ scanner into your app 🎉

If this tutorial has piqued your interest in integrating document scanning functionalities into your Capacitor app, make sure to take a look at the other neat features in the Capacitor SDK’s documentation – or run our example project for a more hands-on experience.

Should you have questions about this tutorial or run into any issues, we’re happy to help! Just shoot us an email via tutorial-support@scanbot.io.

Happy scanning! 🤳

Related blog posts

Experience our demo apps

Barcode Icon Art

Barcode Scanner SDK

Scan 1D and 2D barcodes reliably in under 0.04s. Try features like Batch Scanning, Scan & Count, and our AR Overlays.

Launch Web Demo

Scan the code to launch the web demo on your phone.

Web QR Code

Also available to download from:

Document Icon Art

Document Scanner SDK

Scan documents quickly and accurately with our free demo app. Create crisp digital scans in seconds.

Launch Web Demo

Scan the code to launch the web demo on your phone.

Black and white QR code. Scan this code for quick access to information.

Also available to download from:

Data_capture Icon Art

Data Capture Modules

Try fast, accurate data capture with our demo app. Extract data from any document instantly – 100% secure.

Launch Web Demo

Scan the code to launch the web demo on your phone.

Black and white QR code. Scan this quick response code with your smartphone.

Also available to download from: