Building an Expo MRZ Scanner with React Native

In this tutorial, we’ll use React Native and the Expo framework to build a cross-platform app for Android and iOS that extracts data from machine-readable zones on ID cards and similar documents.

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

Building our app involves the following steps:

1. Preparing the project
2. Installing the MRZ Scanner SDK
3. Initializing the SDK
4. Implementing the scanning feature

import { useCallback } from "react";
import { Alert, Button } from "react-native";
import ScanbotSDK, { MRZ } from 'react-native-scanbot-sdk';
import { MrzScannerScreenConfiguration, startMRZScanner } from "react-native-scanbot-sdk/ui_v2";

export default function Index() {

  const onMrzScanner = useCallback(async () => {
    try {
      if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
        return;
      }

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

      if (mrzResult.status === 'OK' && mrzResult.data && mrzResult.data.mrzDocument !== null) {
        const mrz = new MRZ(mrzResult.data.mrzDocument);

        Alert.alert(
          "MRZ Data:",
          `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.error(e.message);
    }
  }, []);

  return (
    <Button title={"Start MRZ Scanner"} onPress={onMrzScanner} />
  );
}

Requirements

Before starting app development with React Native, you need to set up your local development environment. You’ll also need a real device to get the full benefits from using the SDK. You can find the steps for preparing your local environment in the Expo documentation.

Step 1: Prepare the project

1. Create a new Expo project

First, let’s create our Expo app using the Expo CLI, which will walk us through the setup process.

To create an Expo app, run the following command in the terminal:

npx create-expo-app@latest

When prompted, name your app, e.g., “expo-mrz-scanner”. Then navigate into the project directory.

cd expo-mrz-scanner

2. Remove boilerplate code

The Expo CLI has generated some screens to ensure the app isn’t empty. The generated code can be quickly removed by running the following command:

npm run reset-project

Now the app directory only contains an index file, which is our only screen, and a _layout.tsx file.

3. Generate the native projects

To install expo-dev-client, we need to run the following command:

npx expo install expo-dev-client

Afterward, we generate our iOS and Android projects with:

npx expo prebuild

Step 2: Install the MRZ Scanner SDK

Next, install the Scanbot React Native SDK.

npm install react-native-scanbot-sdk

Now we just need to make the necessary native changes to the projects.

You can use the SDK’s config plugin or manually configure the native projects. We’ll showcase both so you can pick the method you prefer.

Method A: Expo config plugin

To utilize the plugin, add the following to your app.json file:

"plugins": [
  [
    "react-native-scanbot-sdk",
    {
      "iOSCameraUsageDescription": "MRZ scanning permission",
      "largeHeap": true,
      "mavenURLs": true
    }
  ]
],

Then run:

npx expo prebuild

Now you’re all set. You can skip the Android and iOS native changes when using this plugin.

Method B: Manual configuration

Alternatively, you can also apply the changes to the native projects manually.

Android

Let’s enable the largeHeap flag to process more memory intensive operations.

Set the property android:largeHeap="true" in the <application> tag in the app’s Manifest in android/app/src/main/AndroidManifest.xml.

For development builds, we also need to add our Maven package URLs in android/build.gradle

allprojects {
    repositories {
      // ... other maven rpositories
      maven { url "https://nexus.scanbot.io/nexus/content/repositories/releases/" }
      maven { url "https://nexus.scanbot.io/nexus/content/repositories/snapshots/" }
    }
}

iOS

For iOS, we need to include a description for the camera permission in ios/{projectName}/Info.plist anywhere inside the element:

<key>NSCameraUsageDescription</key>
<string>Grant camera access to scan an MRZ.</string>

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

Step 3: Initializing 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.

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

There are several ways to initialize the SDK, depending on your use case. In this tutorial, we’re going to initialize the SDK inside a useEffect in our app/_layout.tsx file.

So _layout.tsx would look like this:

import {Stack} from "expo-router";
import {useEffect} from "react";
import ScanbotSDK from 'react-native-scanbot-sdk';

export default function RootLayout() {

    useEffect(() => {
        ScanbotSDK
            .initializeSDK({licenseKey: ""})
            .then(result => console.log(result))
            .catch(err => console.log(err));
    }, []);

    return (
        <Stack>
            <Stack.Screen name="index"/>
        </Stack>
    );
}

Step 4: Implementing the scanning feature

In app/index.tsx, we’re going to add a button that will call up the scanning interface.

First, let’s add the necessary imports for the integration.

import { useCallback } from "react";
import { Alert, Button } from "react-native";
import ScanbotSDK, { MRZ } from 'react-native-scanbot-sdk';
import { MrzScannerScreenConfiguration, startMRZScanner } from "react-native-scanbot-sdk/ui_v2";

Since we ran the reset-project command earlier, the file should only contain a single view with a Text component. Let’s replace it with a Button component.

<Button title={"Start MRZ Scanner"} onPress={onMrzScanner} />

We also need to define onMrzScanner, which will start the scanning process.

const onMrzScanner = useCallback(async () => {
  try {

    // Check license status and return early if the license is not valid
    if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
      return;
    }

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

    if (mrzResult.status === 'OK' && mrzResult.data && mrzResult.data.mrzDocument !== null) {

      // Instantiate MRZ with the GenericDocument from the result
      const mrz = new MRZ(mrzResult.data.mrzDocument);
    }
  } catch (e: any) {
    console.error(e.message);
  }
}, []);

Finally, we’re going to access the MRZ data and show the values in an alert.

// ...
const mrz = new MRZ(mrzResult.data.mrzDocument);

Alert.alert(
  "MRZ Data:",
  `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}`
);
// ...

Your final index.tsx will look like this:

import { useCallback } from "react";
import { Alert, Button } from "react-native";
import ScanbotSDK, { MRZ } from 'react-native-scanbot-sdk';
import { MrzScannerScreenConfiguration, startMRZScanner } from "react-native-scanbot-sdk/ui_v2";

export default function Index() {

  const onMrzScanner = useCallback(async () => {
    try {
      if (!(await ScanbotSDK.getLicenseInfo()).isLicenseValid) {
        return;
      }

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

      if (mrzResult.status === 'OK' && mrzResult.data && mrzResult.data.mrzDocument !== null) {
        const mrz = new MRZ(mrzResult.data.mrzDocument);

        Alert.alert(
          "MRZ Data:",
          `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.error(e.message);
    }
  }, []);

  return (
    <Button title={"Start MRZ Scanner"} onPress={onMrzScanner} />
  );
}

Now run the app on your Android or iOS device using the following commands:

For Android:

npx expo run:android --device

For iOS:

npx expo run:ios --device

Conclusion

And that’s it! You’ve successfully built a cross-platform MRZ scanning app with React Native and Expo 🎉

If this tutorial has piqued your interest in integrating scanning functionalities into your React Native app, make sure to take a look at the SDK’s other neat features in the Scanbot React Native SDK 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! 🤳