# MRZ Scanner User Guide (Flutter Edition)
This user guide will explore using the Dynamsoft MRZ Scanner (Flutter Edition) to easily integrate the ability to read MRZ data from identity documents such as passports and ID cards. The Dynamsoft MRZ Scanner comes with a ready-to-use setup that simplifies the development process, allowing you to focus on other aspects of the application.
> [!IMPORTANT]
> For the full sample code, visit the [ScanMRZ sample on GitHub](https://github.com/Dynamsoft/mrz-scanner-mobile-flutter).
## Supported Machine-Readable Travel Document Types
The Machine Readable Travel Documents (MRTD) standard specified by the International Civil Aviation Organization (ICAO) defines how to encode information for optical character recognition on official travel documents.
Currently, the SDK supports three types of MRTD:
> [!NOTE]
> If you need support for other types of MRTDs, our SDK can be easily customized. Please contact our [support team](https://www.dynamsoft.com/contact).
### ID (TD1 Size)
The MRZ (Machine Readable Zone) in TD1 format consists of 3 lines, each containing 30 characters.
### ID (TD2 Size)
The MRZ (Machine Readable Zone) in TD2 format consists of 2 lines, with each line containing 36 characters.
### Passport (TD3 Size)
The MRZ (Machine Readable Zone) in TD3 format consists of 2 lines, with each line containing 44 characters.
## System Requirements
* Latest [Flutter SDK](https://flutter.dev/)
* Android
* Supported OS: Android 5.0 (API Level 21) and higher
* Supported ABI: armeabi-v7a, arm64-v8a, x86 and x86_64
* Development Environment: Android Studio Meerkat (2024.3.1); Java 17+; Gradle 8.0+
* iOS
* Supported OS: iOS 13+
* Supported ABI: arm64 and x86_64
* Development Environment: Xcode 13+ (Xcode 14.1+ recommended)
## Including the Library
A valid license key is required to use the SDK. If you are just getting started, request a free 30-day trial license below:
The license will be sent to your email immediately.
> [!NOTE]
>
> - The license string above grants a time-limited free trial which requires a network connection.
> - You can request a 30-day trial license via the [Request a Trial License](https://www.dynamsoft.com/customer/license/trialLicense?product=mrz&utm_source=guide&package=flutter){:target="_blank"} link.
## Building the MRZ Scanner Application
The following steps build the **ScanMRZ** sample app. You can also download the complete project from the [GitHub repo](https://github.com/Dynamsoft/mrz-scanner-mobile-flutter).
### Step 1: Create a New Project
Create a new Flutter project and open the project in your IDE:
```bash
flutter create scan_mrz
```
Navigate to `lib/main.dart` — this is where the implementation will go.
### Step 2: Add the SDK
Run the following command from the project root to add `dynamsoft_mrz_scanner_bundle_flutter`:
```bash
flutter pub add dynamsoft_mrz_scanner_bundle_flutter
```
Then run the command to install all dependencies:
```bash
flutter pub get
```
## Building the MRZ Scanner Widget
Now that the package is added, it's time to start building the `MRZScanner` Widget using the SDK.
### Importing the Library
To use the MRZScanner API, please import `dynamsoft_mrz_scanner_bundle_flutter` in your dart file:
```dart
import 'package:dynamsoft_mrz_scanner_bundle_flutter/dynamsoft_mrz_scanner_bundle_flutter.dart';
```
### Quick Start
The code below shows the simplest function implementation to initialize and start the MRZ Scanner
```dart
import 'package:dynamsoft_mrz_scanner_bundle_flutter/dynamsoft_mrz_scanner_bundle_flutter.dart';
void _launchMrzScanner() async {
var config = MRZScannerConfig(
license: "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9",
);
MRZScanResult mrzScanResult = await MRZScanner.launch(config);
if(mrzScanResult.status == EnumResultStatus.finished) {
MRZData data = mrzScanResult.mrzData!;
// do something with the data
}
}
```
You can call the above function anywhere (e.g., when the app starts, on a button click, etc.) to achieve the effect:
open an MRZ scanning interface, and after scanning is complete, close the interface and return the result.
This next code snippet is the **full Hello World implementation** that uses the above `_launchMrzScanner` function. This is done in *main.dart* but can be used as a reference for your own implementation, whether it is in *main.dart* or any other page.
```dart
import 'package:dynamsoft_mrz_scanner_bundle_flutter/dynamsoft_mrz_scanner_bundle_flutter.dart';
import 'package:flutter/material.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
// This widget is the root of your application.
@override
Widget build(BuildContext context) {
return MaterialApp(
title: 'Scan MRZ',
theme: ThemeData(
colorScheme: ColorScheme.fromSeed(seedColor: Colors.orange),
),
home: const MyHomePage(title: 'Scan MRZ'),
);
}
}
class MyHomePage extends StatefulWidget {
final String title;
const MyHomePage({super.key, required this.title});
@override
State createState() => _MyHomePageState();
}
class _MyHomePageState extends State {
String _displayString = "";
void _launchMrzScanner() async {
var config = MRZScannerConfig(
license: "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9",
);
MRZScanResult mrzScanResult = await MRZScanner.launch(config);
setState(() {
if(mrzScanResult.status == EnumResultStatus.canceled) {
_displayString = "Scan canceled";
} else if(mrzScanResult.status == EnumResultStatus.exception) {
_displayString = "ErrorCode: ${mrzScanResult.errorCode}\n\nErrorString: ${mrzScanResult.errorMessage}";
} else { //EnumResultStatus.finished
MRZData data = mrzScanResult.mrzData!;
_displayString = "Name:\t${data.firstName} ${data.lastName}\n\n"
"Sex: ${data.sex.substring(0,1).toUpperCase() + data.sex.substring(1)}\n\n"
"Age: ${data.age}\n\n"
"Document Type: ${data.documentType}\n\n"
"Document Number: ${data.documentNumber}\n\n"
"Issuing State: ${data.issuingState}\n\n"
"Nationality: ${data.nationality}\n\n"
"Date of Birth(YYYY-MM-DD): ${data.dateOfBirth}\n\n"
"Date of Expiry(YYYY-MM-DD): ${data.dateOfExpire}";
}
});
}
@override
Widget build(BuildContext context) {
return Scaffold(
appBar: AppBar(
backgroundColor: Theme.of(context).colorScheme.inversePrimary,
title: Text(widget.title),
),
body: Center(
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text(
_displayString,
style: Theme.of(context).textTheme.bodyLarge,
),
SizedBox(height: 20), // Add a spacing of 20
TextButton(
onPressed: _launchMrzScanner,
style: TextButton.styleFrom(
backgroundColor: Colors.orange,
foregroundColor: Colors.white,
),
child: const Text("Scan an MRZ"),
),
],
),
)
);
}
}
```
> [!NOTE]
>
>- The license string here grants a time-limited free trial which requires network connection to work.
>- You can request a 30-day trial license via the [Trial License portal](https://www.dynamsoft.com/customer/license/trialLicense?product=mrz&utm_source=github&package=mobile).
### MRZ Result and Data
Once the scan process completes and the MRZ Scanner successfully recognizes a MRZ, a `MRZScanResult` is produced, representing all of the decrypted data contained within the MRZ.
[`MRZScanResult`](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/mrz-scan-result.md) has the following properties:
- **resultStatus**: The status of the MRZ scan result, of type [`EnumResultStatus`](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/result-status.md).
- *finished*: The MRZ scan was successful.
- *canceled*: The MRZ scanning activity is closed before the process is finished.
- *exception*: Failed to start MRZ scanning or an error occurs when scanning the MRZ.
- **errorCode**: The error code indicates if something went wrong during the MRZ scanning process (0 means no error). Only defined when the `resultStatus` is `exception`.
- **errorString**: The error message associated with the error code if an error occurs during MRZ scanning process. Only defined when the `resultStatus` is `exception`.
- **data**: The parsed MRZ data as a `MRZData` object.
[`MRZData`](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/mrz-data.md) holds the actual decrypted data of the MRZ result, and it comes with the following fields:
- **documentType**: The type of MRZ document, which would either be `EnumDocumentType.passport`, `EnumDocumentType.id`, or `EnumDocumentType.all`. You can check out the [Supported Machine-Readable Travel Document Types](#supported-machine-readable-travel-document-types) to learn more.
- **firstName**: The first name of the MRZ document holder.
- **lastName**: The last name of the MRZ document holder.
- **sex**: The sex of the MRZ document holder.
- **issuingState**: The issuing state of the MRZ document.
- **nationality**: The nationality of the MRZ document holder.
- **dateOfBirth**: The date of birth of the MRZ document holder.
- **dateOfExpiry**: The expiry date of the MRZ document.
- **documentNumber**: The MRZ document number.
- **age**: The age of the MRZ document holder.
- **mrzText**: The raw text of the MRZ.
For the full field list, see the [MRZData API reference](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/mrz-data.md).
### Customizing the MRZ Scanner (Optional)
Even though the default settings of the ready-to-use MRZ Scanner is sufficient to cover the majority of MRZ scanning scenarios, the [`MRZScannerConfig`](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/mrz-scanner-config.md) class allows you to change the behaviour of the MRZ Scanner to fit your specific scenario. Using this class can help you customize different UI elements and determine the settings of the scanner engine itself.
To learn of the different ways in which the MRZ scanner can be customized, please refer to the [MRZ Scanner Customization Guide](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/user-guide/customize-mrz-scanner.md).
## Run the Project
### iOS
Before the project can be deployed to a *iOS* device, the camera permissions and the developer signature must first be set. To add the camera permissions to the iOS portion of the app, we recommend first installing the **pods** dependencies to generate the **.xcworkspace** project under the ios folder (`ios/Runner.xcworkspace`). Please run the following commands from the root directory:
```bash
cd ios/
pod install --repo-update
```
Once the pods are installed, *Runner.xcworkspace* should now be generated in the *ios* folder.
#### Camera Permissions
To add the **camera permissions**, open the generated *Runner.xcworkspace* and navigate to the *Info* section of the project settings. Then you must add the "Privacy - Camera Usage Description" key to the list (where you can also assign a string message to show in the alert box).
Connect a physical iOS device, then either select it from the top bar in Xcode and click **Run**, or run from the project root with:
```bash
flutter run
# or
flutter run -d
```
You can list connected device IDs with `flutter devices`.
In order to deploy the app to a iOS device, we recommend doing it via Xcode by using the `Runner.xcworkspace` project that was generated when the pods were installed. Since the camera permissions are taken care of, all you need to do is properly configure the *Signing & Capabilities* section of the project settings. Should the iOS device be connected to the computer, you can now run and deploy the app to the device.
If everything is set up correctly, you should see the app running on your device.
### Android
#### Deploying to Device
Go to the project root folder, open a new terminal and run the following command:
```bash
flutter run
# or
flutter run -d
```
You can get the IDs of all connected (physical) devices by running the command `flutter devices` in the terminal.
## Full Sample Code
The full sample code is available [here](https://github.com/Dynamsoft/capture-vision-flutter-samples/tree/main/ScanMRZ).
- **Samples** — Explore the complete [ScanMRZ sample on GitHub](https://github.com/Dynamsoft/mrz-scanner-mobile-flutter).
- **Customize** — Learn how to configure document type, UI elements, and image capture in the [Customize MRZ Scanner](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/user-guide/customize-mrz-scanner.md) guide.
- **API Reference** — Browse the full [Flutter API Reference](https://www.dynamsoft.com/mrz-scanner/docs/mobile/programming/flutter/api-reference/index.md) for all classes and methods.
- **Support** — Contact the [Dynamsoft Support Team](https://www.dynamsoft.com/contact) for help or custom requirements.
