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 ScanningModulesConfig.ts.

Default BlinkID UX (camera scanning)

const sdkSettings: BlinkIdSdkSettings = {
  licenseKey,
  downloadResources: true,
};

const scanningUxSettings: BlinkIdScanningUxSettings = {
  showHelpButton: true,
  showOnboardingDialog: true,
  allowHapticFeedback: true,
  preferredCamera: 'back',
};

const classFilter = {
  includeDocuments: [
    { country: Country.Croatia, documentType: DocumentType.Id },
    { country: Country.USA, region: Region.Texas, documentType: DocumentType.Dl },
  ],
};

try {
  const result: BlinkIdScanningResult = await performScan({
    sdkSettings,
    sessionSettings,
    scanningUxSettings,
    classFilter,
    // redactionSettingsResolver, // optional — see Document redaction
  });

  console.log(result.firstName?.value);
  console.log(result.firstDocumentImage); // base64, if enabled
} catch (error) {
  console.log(`Error during scan: ${error}`);
}

BlinkID DirectAPI (static images)

DirectAPI extracts data from Base64-encoded static images instead of using the camera UI.

• Pass two images with scanningMode: 'automatic' (front side first, back side second).
• Pass one image with scanningMode: 'single'.
• Set documentCaptureModule.inputImageCropped: true when images are already cropped and perspective-corrected.

const firstImageBase64 = 'your-base64-image';
const secondImageBase64 = 'your-base64-image'; // optional for single-side

try {
  const result = await performDirectApiScan({
    sdkSettings: { licenseKey, downloadResources: true },
    sessionSettings: {
      scanningMode: 'automatic',
      scanningSettings: {
        documentCaptureModule: {
          documentImageReturnEnabled: true,
          inputImageCropped: false,
        },
        mrzModule: {},
        barcodeModule: { pdf417ScanningEnabled: true, qrScanningEnabled: true },
        vizModule: {},
      },
    },
    firstImage: firstImageBase64,
    secondImage: secondImageBase64,
    // redactionSettings, // optional — see Document redaction
  });

  console.log(result.fullName?.value);
} catch (error) {
  console.log(`Error during scan: ${error}`);
}

Document redaction

In v8000, anonymization has been renamed to redaction. For camera scanning, use a RedactionSettingsResolver to apply per-document redaction rules. For DirectAPI, pass a single RedactionSettings object.

import { FieldType, type RedactionSettingsResolver } from '@microblink/blinkid-react-native';

const redactionSettingsResolver: RedactionSettingsResolver = {
  documentRedactionList: [
    {
      mode: 'fullResult',
      fields: [FieldType.FirstName, FieldType.LastName],
      documentNumberRedactionSettings: {
        prefixDigitsVisible: 0,
        suffixDigitsVisible: 1,
      },
      redactMrzResult: false,
      redactBarcodeResult: false,
      documentFilter: {
        country: Country.USA,
        region: Region.California,
        documentType: DocumentType.Id,
      },
    },
  ],
};

// Camera scanning — pass redactionSettingsResolver to performScan
await performScan({ sdkSettings, sessionSettings, redactionSettingsResolver });

// DirectAPI — pass redactionSettings to performDirectApiScan
await performDirectApiScan({
  sdkSettings,
  sessionSettings,
  firstImage: firstImageBase64,
  redactionSettings: {
    mode: 'fullResult',
    fields: [FieldType.DocumentNumber],
    redactMrzResult: false,
    redactBarcodeResult: false,
  },
});

Redaction modes: none, imageOnly, resultFieldsOnly, fullResult.

Plugin specifics

The BlinkID plugin implementation is located in the src folder here, while platform-specific implementation is located in the android and ios folders.

Scanning methods

Currently, the BlinkID plugin contains two main scanning methods: performScan and performDirectApiScan.

The performScan method

Launches the BlinkID scanning process with the default UX.

Recommended call style — single settings object:

performScan({
  sdkSettings,           // BlinkIdSdkSettings (required)
  sessionSettings,       // BlinkIdSessionSettings (required)
  scanningUxSettings,    // BlinkIdScanningUxSettings (optional)
  classFilter,           // ClassFilter (optional)
  redactionSettingsResolver, // RedactionSettingsResolver (optional)
});

Parameter	Description
sdkSettings	License key, resource download configuration
sessionSettings	Scanning mode, module settings, timeouts
scanningUxSettings	Help button, onboarding dialog, haptic feedback, preferred camera
classFilter	Include/exclude documents by country, region, and type
redactionSettingsResolver	Per-document redaction rules applied before the result is finalized

Returns BlinkIdScanningResult (implementation).

The performDirectApiScan method

Extracts document information from static Base64 images.

performDirectApiScan({
  sdkSettings,        // BlinkIdSdkSettings (required)
  sessionSettings,    // BlinkIdSessionSettings (required)
  firstImage,         // Base64 string (required)
  secondImage,        // Base64 string (optional)
  redactionSettings,  // RedactionSettings (optional)
});

Returns BlinkIdScanningResult (implementation).

SDK loading & unloading

The loadBlinkIdSdk method

Creates or retrieves the BlinkID SDK instance. Handles initialization, resource downloading, and license verification. Call in advance to reduce first-scan latency.

await loadBlinkIdSdk({ sdkSettings: { licenseKey, downloadResources: true } });

If you do not call loadBlinkIdSdk, it is invoked automatically when a scan starts.

The unloadBlinkIdSdk method

Terminates the SDK and releases resources. Must reinitialize before the next scan.

await unloadBlinkIdSdk({ deleteCachedResources: false });

Set deleteCachedResources to true to also delete downloaded and cached SDK resources from the device.

unloadBlinkIdSdk is called automatically after each successful scan session.

BlinkID Settings

Setting	Type	Description
SDK settings	BlinkIdSdkSettings	License key, resource download, proxy URL
Session settings	BlinkIdSessionSettings	Scanning mode, module settings, step/inactivity timeouts (ms; 0 disables)
Scanning settings	BlinkIdScanningSettings	Module configuration (see below)
UX settings	BlinkIdScanningUxSettings	UI customization during scanning
Class filter	ClassFilter	Document include/exclude rules
Redaction	RedactionSettings / RedactionSettingsResolver	Field and image redaction

Scanning module settings

| Module | Type | Key settings | | --- | | --- | | Document capture | DocumentCaptureModuleSettings | Image quality (blur, glare, tilt, lighting), cropped/input image return, face extraction, passport data page only | | MRZ | MrzModuleSettings | presenceMandatory | | Barcode | BarcodeModuleSettings | PDF417, QR, retail barcode types, barcode image return | | VIZ | VizModuleSettings | Signature extraction, character validation, result aggregation |

The blinkIdSettings.ts and types.ts files contain all available settings with inline documentation.

BlinkID Results

The scanning result is stored in BlinkIdScanningResult. It contains extracted data and images from the document.

Key result members:

1. Document class info — documentClassInfo (DocumentClassInfo)
2. Data match information — dataMatchResult (DataMatchResult)
3. Per-side results — subResults (SingleSideScanningResult[]) — contains VIZ, MRZ, and barcode data per side
4. Aggregated fields — top-level fields such as firstName, lastName, documentNumber, etc.
5. Images — firstDocumentImage, secondDocumentImage, faceImage, signatureImage, firstInputImage, secondInputImage, barcodeImage

Each SingleSideScanningResult contains:

• viz — Visual Inspection Zone data
• mrz — Machine Readable Zone data
• barcode — Barcode data
• documentImage, faceImage, signatureImage, inputImage

Full result types: blinkIdResult.ts and types.ts.

What's new in v8000

BlinkID v8000 introduces a modular recognition architecture. Instead of flat scanning settings and fallback recognition modes, extraction is driven by four independent modules that you enable and configure separately:

Module	Purpose
Document capture	Document detection, image quality checks (blur, glare, tilt, lighting), and cropped image extraction
MRZ	Machine Readable Zone detection and parsing (passports, visas, ID cards)
Barcode	1D/2D barcode detection and parsing (PDF417, QR, retail codes, and more)
VIZ	Visual Inspection Zone field extraction, character validation, and signature images

Other notable changes:

• Settings are plain TypeScript objects (no class constructors).
• Scanning methods accept a single settings object (recommended) or legacy positional arguments.
• Anonymization has been renamed to redaction (RedactionSettings, RedactionSettingsResolver).
• Image return and quality settings moved from CroppedImageSettings into documentCaptureModule and vizModule.
• Detection levels (DetectionLevel) are replaced by sensitivity levels (SensitivityLevel: off, low, mid, high).
• Scanning sessions include step and inactivity timeouts on BlinkIdSessionSettings (milliseconds; defaults 60000 and 10000). Set either to 0 to disable.

Migrating from v7.x

If you are upgrading from @microblink/blinkid-react-native@7.x (e.g. 7.7.0), the following changes apply.

Settings are plain objects

// v7
const sdkSettings = new BlinkIdSdkSettings(licenseKey);
sdkSettings.downloadResources = true;

// v8000
const sdkSettings = { licenseKey, downloadResources: true };

Modular scanning settings

Flat v7 settings map to module settings in v8000:

v7	v8000
blurDetectionLevel	documentCaptureModule.blurSensitivityLevel
glareDetectionLevel	documentCaptureModule.glareSensitivityLevel
tiltDetectionLevel	documentCaptureModule.tiltSensitivityLevel
skipImagesWithBlur	documentCaptureModule.imageWithBlurRejected
skipImagesWithGlare	documentCaptureModule.imageWithGlareRejected
croppedImageSettings.returnDocumentImage	documentCaptureModule.documentImageReturnEnabled
croppedImageSettings.returnFaceImage	documentCaptureModule.faceImageExtractionEnabled
croppedImageSettings.returnSignatureImage	vizModule.signatureImageExtractionEnabled
croppedImageSettings.dotsPerInch	documentCaptureModule.dotsPerInch
scanCroppedDocumentImage	documentCaptureModule.inputImageCropped
enableCharacterValidation	vizModule.characterValidationEnabled
scanPassportDataPageOnly	documentCaptureModule.passportDataPageScanOnly
anonymizationMode	Use RedactionSettings / RedactionSettingsResolver
recognitionModeFilter / enableBarcodeScanOnly	Enable/disable modules explicitly

Removed types: CroppedImageSettings, AnonymizationMode, DetectionLevel, RecognitionMode.

Method call style

// v7 — positional arguments
await performScan(sdkSettings, sessionSettings, uxSettings, classFilter);

// v8000 — recommended object style
await performScan({ sdkSettings, sessionSettings, scanningUxSettings: uxSettings, classFilter });

// v8000 unload API
await unloadBlinkIdSdk({ deleteCachedResources: false });

BlinkID Android SDK v8000 requires Kotlin v2.2.21+. See Android setup for more details.

For the complete migration guide with all setting mappings, see Migrate to v8000.

Additional information and Support

For any additional questions and information, feel free to contact us here, or directly to the Support team at support@microblink.com.