BlinkID React Native plugin

The BlinkID SDK is a comprehensive solution for implementing secure document scanning in React Native cross-platform applications. It offers powerful capabilities for capturing and analyzing a wide range of identification documents. The React Native plugin wraps the native BlinkID SDK and BlinkID UX modules, providing a complete, ready-to-use scanning experience with a user-friendly interface.

Please note that, for maximum performance and full access to all features, it’s best to go with one of our native SDKs (for iOS or Android).

However, since the wrapper is open source, you can add the features you need on your own.

Current version: @microblink/blinkid-react-native@8000.0.0 (BlinkID SDK v8000).
If you are upgrading from v7.x, see Migrating from v7.x.

Table of contents

• Licensing
• Requirements
• Quickstart with the sample application
  • Android sample application
    • On an emulator
    • On a physical device via USB
  • iOS sample application
• Plugin integration
  • Android setup
  • iOS setup
  • Permissions
• Plugin usage
  • Imports and license key
  • Configure scanning modules
  • Default BlinkID UX (camera scanning)
  • BlinkID DirectAPI (static images)
  • Document redaction
• Plugin specifics
  • Scanning methods
  • SDK loading & unloading
  • BlinkID settings
  • BlinkID results
• What's new in v8000
  • Migrating from v7.x
• Additional information and Support

Licensing

A valid license key is required to initialize the BlinkID plugin.

A free trial license key can be requested after registering at the Microblink Developer Hub.

Requirements

BlinkID React Native v8000 was built and tested with React Native v0.82.x

• The BlinkID React Native SDK is also compatible with React Native applications running on the old architecture as it contains backward compatibility with Native Module implementation.

For additional help with React-Native setup, view the official documentation here.

Device requirements

The BlinkID React Native plugin requires:

• iOS version 16.0 and above
• Android API version 24 and above

For more detailed information about the BlinkID Android and iOS requirements, view the native SDK documentation here (Android & iOS).

Quickstart with the sample application

The sample application demonstrates how the BlinkID plugin is implemented and shows how to configure scanning modules and obtain results.

It contains the implementation for:

1. Default BlinkID UX scanning — camera-based scanning with configurable modules.
2. Multiside DirectAPI scanning — extracting document information from two static images (from the gallery).
3. Singleside DirectAPI scanning — extracting document information from a single static image (from the gallery).

The sample also includes a module settings panel where you can toggle and configure the document capture, barcode, MRZ, and VIZ modules, along with optional class filters and redaction settings.

To obtain and run the sample application, follow the steps below. Make sure you have Node & Watchman installed before running the sample application:

# install Watchman
brew install watchman

# install Node
brew install node

To install & run the sample application:

1. Git clone the repository:

git clone https://github.com/microblink/blinkid-react-native.git

2. Position to the obtained blinkid-react-native folder

cd blinkid-react-native

3. Run the initBlinkIdReactNativeSample.sh script to create a sample app, with required configurations applied.

./initBlinkIdReactNativeSample.sh

4. After the script finishes running, position to the BlinkIdSample folder.

Android sample application

Running the sample application on Android

On an emulator:

1. Execute the following command:

npx react-native start

2. In another terminal, run:

npx react-native run-android

Alternative: Run directly via Android Studio:

1. Execute the following command:

npx react-native start

2. Open the android folder via Android Studio in the BlinkIdSample folder to run the Android sample application.

On a physical device via USB:

1. Connect your device via USB and enable USB debugging in Developer Options.
2. Forward the Metro bundler port:

adb reverse tcp:8081 tcp:8081

3. Start Metro in one terminal:

npx react-native start

4. In another terminal, build and run on the device:

npx react-native run-android

or open it in Android Studio and run it on the physical device from there.

iOS sample application

Running the sample application on iOS

1. For running the sample application on iOS, execute the following command:

npx react-native start

2. Open the BlinkIdSample.xcworkspace located in the ios folder
3. Set your development team
4. Press run

Plugin integration

1. To add the BlinkID plugin to a React Native project, first create an empty project if needed:

npx @react-native-community/cli init YourAppName --package-name YourPackageName --title YourAppTitle --version "0.82.0"

2. Install the @microblink/blinkid-react-native dependency:

npm install --save @microblink/blinkid-react-native@8000.0.0

3. Complete the platform-specific setup below.

Android setup

Add Maven Central to your project repositories.

In android/settings.gradle (or your root build.gradle, depending on your React Native version):

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

Ensure your app uses Kotlin v2.2.21 or newer, minSdkVersion 24 or newer, and compileSdkVersion 36 or newer. Use the Android Gradle Plugin and Gradle versions shipped with your React Native release (for example, React Native 0.82.x uses AGP 8.12 and Gradle 9.0).

blinkid-ux ships its Compose-based scanning UI as a precompiled AAR, so client apps do not need to enable the Compose compiler plugin, buildFeatures.compose, or a Compose BOM unless they compile their own Compose code.

Set the Kotlin version in your project-level android/build.gradle:

buildscript {
    ext {
        kotlinVersion = "2.2.21"
    }
}

The sample initialization script (initBlinkIdReactNativeSample.sh) contains the complete, tested Android configuration if you need a reference implementation.

iOS setup

1. Set the minimum iOS deployment target to 16.0 in your ios/Podfile:

platform :ios, '16.0'

2. Install pods:

cd ios && pod install

The plugin ships with vendored BlinkID.xcframework and BlinkIDUX.xcframework frameworks.

Permissions

Add the required usage descriptions to your app:

iOS — in Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for document scanning</string>

If you use DirectAPI with images from the photo library, also add:

<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required for document image upload</string>

Android — camera permission is typically merged from the BlinkID UX library. If needed, add to AndroidManifest.xml:

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

Plugin usage

Note: The plugin usage process can be found in the sample app App.tsx file here.

Imports and license key

After adding the blinkid-react-native dependency, import the API and set your platform-specific license key:

import { Platform } from 'react-native';
import {
  performScan,
  performDirectApiScan,
  loadBlinkIdSdk,
  unloadBlinkIdSdk,
  Country,
  DocumentType,
  Region,
  type BlinkIdScanningResult,
  type BlinkIdSdkSettings,
  type BlinkIdSessionSettings,
  type BlinkIdScanningSettings,
  type BlinkIdScanningUxSettings,
} from '@microblink/blinkid-react-native';

const licenseKey = Platform.select({
  ios: 'your-ios-key',
  android: 'your-android-key',
})!;

All settings are plain objects. You do not need class constructors.

Configure scanning modules

Scanning behavior is configured through BlinkIdScanningSettings, which contains up to four module settings. Include only the modules you want to use — omitting a module disables it.

const scanningSettings: BlinkIdScanningSettings = {
  // Document capture: detection, image quality, cropped images
  documentCaptureModule: {
    documentImageReturnEnabled: true,
    faceImageExtractionEnabled: true,
    dotsPerInch: 250,
    blurSensitivityLevel: 'mid',
    imageWithBlurRejected: true,
    glareSensitivityLevel: 'mid',
    imageWithGlareRejected: true,
    passportDataPageScanOnly: true,
  },

  // MRZ extraction (passports, visas, etc.)
  mrzModule: {
    presenceMandatory: false,
  },

  // Barcode extraction (PDF417, QR, etc.)
  barcodeModule: {
    pdf417ScanningEnabled: true,
    qrScanningEnabled: true,
    barcodeImageReturnEnabled: false,
  },

  // VIZ extraction (visual fields on the document)
  vizModule: {
    signatureImageExtractionEnabled: true,
    characterValidationEnabled: true,
    resultAggregationEnabled: true,
  },
  
  // Max character mismatches allowed per field during cross-side data matching (default: 0)
  maxAllowedMismatchesPerField: 0,
};

const sessionSettings: BlinkIdSessionSettings = {
  scanningMode: 'automatic', // or 'single'
  scanningSettings,
  // Timeouts are in milliseconds. Set to 0 to disable.
  stepTimeoutDuration: 60000,       // default: 60 s
  inactivityTimeoutDuration: 10000, // default: 10 s
};

Module-only scanning examples:

• Barcode only — include barcodeModule, omit mrzModule and vizModule.
• Document capture only (similar to BlinkID Capture) — include only documentCaptureModule.

Note: When using PDF417 and QR barcode scanning, enable both pdf417ScanningEnabled and qrScanningEnabled together. The analyzer treats them as a combined detection stage.

For DirectAPI with pre-cropped document images, set documentCaptureModule.inputImageCropped to true.

Module configuration helpers can be found in [Scanning