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.

Building our app involves the following steps:
- Preparing the project
- Installing the Scanbot SDK
- Initializing the SDK
- 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

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