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@8001.0.0(BlinkID SDK v8001).
If you are upgrading from v8000, see What's new in v8001.
If you are upgrading from v7.x, see Migrating from v7.x (then apply the v8001 notes).
- Licensing
- Requirements
- Quickstart with the sample application
- Plugin integration
- Plugin usage
- Plugin specifics
- What's new in v8001
- What's new in v8000
- Additional information and Support
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.
BlinkID React Native v8001 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).
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:
- Default BlinkID UX scanning — camera-based scanning with configurable modules.
- Multiside DirectAPI scanning — extracting document information from two static images (from the gallery).
- 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 nodeTo install & run the sample application:
- Git clone the repository:
git clone https://github.com/microblink/blinkid-react-native.git- Position to the obtained
blinkid-react-nativefolder
cd blinkid-react-native- Run the
initBlinkIdReactNativeSample.shscript to create a sample app, with required configurations applied.
./initBlinkIdReactNativeSample.sh- After the script finishes running, position to the
BlinkIdSamplefolder.
Running the sample application on Android
- Execute the following command:
npx react-native start- In another terminal, run:
npx react-native run-androidAlternative: Run directly via Android Studio:
- Execute the following command:
npx react-native start- Open the
androidfolder via Android Studio in theBlinkIdSamplefolder to run the Android sample application.
- Connect your device via USB and enable USB debugging in Developer Options.
- Forward the Metro bundler port:
adb reverse tcp:8081 tcp:8081- Start Metro in one terminal:
npx react-native start- In another terminal, build and run on the device:
npx react-native run-androidor open it in Android Studio and run it on the physical device from there.
Running the sample application on iOS
- For running the sample application on iOS, execute the following command:
npx react-native start- Open the
BlinkIdSample.xcworkspacelocated in theiosfolder - Set your development team
- Press run
- 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"- Install the
@microblink/blinkid-react-nativedependency:
npm install --save @microblink/blinkid-react-native@8001.0.0- Complete the platform-specific setup below.
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.
- Set the minimum iOS deployment target to 16.0 in your
ios/Podfile:
platform :ios, '16.0'- Install pods:
cd ios && pod installThe plugin ships with vendored BlinkID.xcframework and BlinkIDUX.xcframework frameworks.
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" />Note: The plugin usage process can be found in the sample app App.tsx file here.
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,
refreshLicenseLease,
CountryID,
DocumentTypeID,
RegionID,
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.
Use CountryID / RegionID / DocumentTypeID for class filters and redaction document filters. Nested Country / Region / DocumentType types ({ id?, rawValue }) appear only on scan results (documentClassInfo).
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: {
cropType: 'not-cropped', // camera UX must use not-cropped; see DirectAPI for cropped/unknown
inputImageSelectionStrategy: 'balanced', // camera / video only
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, Aztec, etc.)
barcodeModule: {
pdf417ScanningEnabled: true,
qrScanningEnabled: true,
aztecScanningEnabled: false,
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, omitmrzModuleandvizModule. - Document capture only (similar to BlinkID Capture) — include only
documentCaptureModule.
Note: When using PDF417 and QR barcode scanning, enable both
pdf417ScanningEnabledandqrScanningEnabledtogether. The analyzer treats them as a combined detection stage.
For DirectAPI with pre-cropped document images, set documentCaptureModule.cropType to "cropped" (or "unknown" if cropping is uncertain). Camera scanning (performScan) must keep cropType: "not-cropped".
Module configuration helpers can be found in ScanningModulesConfig.ts.
const sdkSettings: BlinkIdSdkSettings = {
licenseKey,
resourcesConfig: { download: true },
// otaResourcesConfig is optional — native defaults enable OTA update checks
};
const scanningUxSettings: BlinkIdScanningUxSettings = {
showHelpButton: true,
showOnboardingDialog: true,
allowHapticFeedback: true,
preferredCamera: 'back',
};
const classFilter = {
includeDocuments: [
{ country: CountryID.Croatia, documentType: DocumentTypeID.Id },
{ country: CountryID.USA, region: RegionID.Texas, documentType: DocumentTypeID.Dl },
],
};
try {
const result: BlinkIdScanningResult = await performScan({
sdkSettings,
sessionSettings,
scanningUxSettings,
classFilter,
// redactionSettingsResolver, // optional — see Document redaction
});
console.log(result.firstName?.value);
console.log(result.documentClassInfo?.country?.id);
console.log(result.documentClassInfo?.country?.rawValue);
console.log(result.firstDocumentImage); // base64, if enabled
} catch (error) {
console.log(`Error during scan: ${error}`);
}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.cropTypeto"cropped"when images are already cropped and perspective-corrected, or"unknown"when cropping is uncertain. Use"not-cropped"for raw photos.
const firstImageBase64 = 'your-base64-image';
const secondImageBase64 = 'your-base64-image'; // optional for single-side
try {
const result = await performDirectApiScan({
sdkSettings: {
licenseKey,
resourcesConfig: { download: true },
},
sessionSettings: {
scanningMode: 'automatic',
scanningSettings: {
documentCaptureModule: {
documentImageReturnEnabled: true,
cropType: 'not-cropped', // or 'cropped' / 'unknown' for DirectAPI
},
mrzModule: {},
barcodeModule: {
pdf417ScanningEnabled: true,
qrScanningEnabled: true,
aztecScanningEnabled: false,
},
vizModule: {},
},
},
firstImage: firstImageBase64,
secondImage: secondImageBase64,
// redactionSettings, // optional — see Document redaction
});
console.log(result.fullName?.value);
} catch (error) {
console.log(`Error during scan: ${error}`);
}Anonymization was renamed to redaction in v8000. For camera scanning, use a RedactionSettingsResolver to apply per-document redaction rules. For DirectAPI, pass a single RedactionSettings object.
import { FieldType, CountryID, RegionID, DocumentTypeID, 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: CountryID.USA,
region: RegionID.California,
documentType: DocumentTypeID.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.
The BlinkID plugin implementation is located in the src folder here, while platform-specific implementation is located in the android and ios folders.
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, resourcesConfig, optional otaResourcesConfig, proxy URL |
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).
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,
resourcesConfig: { download: 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.
The refreshLicenseLease method
Refreshes the SDK license lease. Can be called periodically to maintain an active license status; the required frequency depends on your license configuration. The SDK must already be initialized (via loadBlinkIdSdk or a scan) before calling this method.
await refreshLicenseLease();| Setting | Type | Description |
|---|---|---|
| SDK settings | BlinkIdSdkSettings |
License key, nested resourcesConfig / otaResourcesConfig, 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 (CountryID / RegionID / DocumentTypeID) |
| Redaction | RedactionSettings / RedactionSettingsResolver |
Field and image redaction |
SDK resource settings (BlinkIdSdkSettings)
| Field | Description |
|---|---|
resourcesConfig |
Base ML resource download/cache (download, serviceUrl, localFolder, requestTimeout as RequestTimeout, iOS bundleIdentifier) |
otaResourcesConfig |
OTA document resources (checkForUpdates, strict, serviceUrl, localFolder, …). Optional; native defaults apply when omitted |
Do not cross-wire base and OTA hosts: base defaults to https://models.cdn.microblink.com/resources; OTA defaults to https://blinkid-ota.microblink.com.
Scanning module settings
| Module | Type | Key settings |
| --- | | --- |
| Document capture | DocumentCaptureModuleSettings | cropType, inputImageSelectionStrategy, image quality, image return, face extraction, passport data page only |
| MRZ | MrzModuleSettings | presenceMandatory |
| Barcode | BarcodeModuleSettings | PDF417, QR, Aztec, 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.
The scanning result is stored in BlinkIdScanningResult. It contains extracted data and images from the document.
Key result members:
- Document class info —
documentClassInfo(DocumentClassInfo) with nestedcountry/region/documentTypeas{ id?, rawValue } - Data match information —
dataMatchResult(DataMatchResult) - Per-side results —
subResults(SingleSideScanningResult[]) — contains VIZ, MRZ, and barcode data per side - Aggregated fields — top-level fields such as
firstName,lastName,documentNumber,ethnicity,parentsInfo, etc. - Images —
firstDocumentImage,secondDocumentImage,faceImage,signatureImage,firstInputImage,secondInputImage,barcodeImage
Each SingleSideScanningResult contains:
viz— Visual Inspection Zone data (includesethnicitywhen available)mrz— Machine Readable Zone databarcode— Barcode datadocumentImage,faceImage,signatureImage,inputImage
Full result types: blinkIdResult.ts and types.ts.
BlinkID v8001 builds on the modular architecture from v8000 with faster document support (including OTA resources), better frame selection, DirectAPI crop handling, Aztec barcodes, and nested document class info.
Highlights for React Native:
| Area | Change |
|---|---|
| SDK settings | Flat resource fields → nested resourcesConfig; new optional otaResourcesConfig |
| Document class info | country / region / documentType are { id?, rawValue } (filters still use flat CountryID / RegionID / DocumentTypeID) |
| Document capture | inputImageCropped → cropType; added inputImageSelectionStrategy |
| Barcode | aztecScanningEnabled |
| Results | ethnicity; ParentInfo.fullName; FieldType.Ethnicity / ParentFullName |
// v8000
const sdkSettings = { licenseKey, downloadResources: true };
// v8001
const sdkSettings: BlinkIdSdkSettings = {
licenseKey,
resourcesConfig: { download: true },
otaResourcesConfig: {
checkForUpdates: true, // default
strict: false, // default — set true to fail init on OTA download errors
},
};| v8000 (flat) | v8001 |
|---|---|
downloadResources |
resourcesConfig.download |
resourceDownloadUrl |
resourcesConfig.serviceUrl |
resourceLocalFolder |
resourcesConfig.localFolder |
resourceRequestTimeout |
resourcesConfig.requestTimeout (RequestTimeout, milliseconds) |
bundleIdentifier |
resourcesConfig.bundleIdentifier (iOS) |
Do not cross-wire hosts: base resources use https://models.cdn.microblink.com/resources; OTA uses https://blinkid-ota.microblink.com.
resourcesConfig.requestTimeout and otaResourcesConfig.requestTimeout accept a RequestTimeout object (milliseconds). Omit requestTimeout to use native defaults (30 seconds per timeout on current BlinkID native SDKs). Omit individual fields inside requestTimeout to keep the native default for that timeout.
resourcesConfig: {
download: true,
requestTimeout: {
connectionTimeoutMilliseconds: 30000,
writeTimeoutMilliseconds: 30000,
readTimeoutMilliseconds: 30000,
},
},
otaResourcesConfig: {
requestTimeout: {
connectionTimeoutMilliseconds: 30000,
readTimeoutMilliseconds: 60000,
}, // write timeout uses native default when omitted
},// v8000
documentCaptureModule: { inputImageCropped: true }
// v8001 — DirectAPI only for cropped/unknown
documentCaptureModule: { cropType: 'cropped' } // or 'unknown' | 'not-cropped'Camera UX (performScan) must use cropType: 'not-cropped'.
const countryId = result.documentClassInfo?.country?.id; // CountryID when known
const countryRaw = result.documentClassInfo?.country?.rawValue; // always set when country presentFull changelog (documents, bug fixes, API details): Release notes.md and platform release notes.
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
CroppedImageSettingsintodocumentCaptureModuleandvizModule. - Detection levels (
DetectionLevel) are replaced by sensitivity levels (SensitivityLevel:off,low,mid,high). - Scanning sessions include step and inactivity timeouts on
BlinkIdSessionSettings(milliseconds; defaults60000and10000). Set either to0to disable.
If you are upgrading from @microblink/blinkid-react-native@7.x (e.g. 7.7.0), the following changes apply.
// v7
const sdkSettings = new BlinkIdSdkSettings(licenseKey);
sdkSettings.downloadResources = true;
// v8000 (flat resource fields)
const sdkSettings = { licenseKey, downloadResources: true };
// v8001 (nested resources — preferred)
const sdkSettings = {
licenseKey,
resourcesConfig: { download: true },
};Flat v7 settings map to module settings in v8000 (still valid in v8001; use cropType instead of inputImageCropped):
| v7 | v8000 / v8001 |
|---|---|
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.cropType ("cropped" / "not-cropped" / "unknown") |
enableCharacterValidation |
vizModule.characterValidationEnabled |
scanPassportDataPageOnly |
documentCaptureModule.passportDataPageScanOnly |
anonymizationMode |
Use RedactionSettings / RedactionSettingsResolver |
recognitionModeFilter / enableBarcodeScanOnly |
Enable/disable modules explicitly |
Removed types: CroppedImageSettings, AnonymizationMode, DetectionLevel, RecognitionMode.
// v7 — positional arguments
await performScan(sdkSettings, sessionSettings, uxSettings, classFilter);
// v8000 / v8001 — recommended object style
await performScan({ sdkSettings, sessionSettings, scanningUxSettings: uxSettings, classFilter });// unload API
await unloadBlinkIdSdk({ deleteCachedResources: false });BlinkID Android SDK requires Kotlin v2.2.21+. See Android setup for more details.
After migrating from v7 to the modular API, also apply What's new in v8001 (nested resourcesConfig / OTA, cropType, nested class info).
For the complete native migration guide from v7, see Migrate to v8000.
For any additional questions and information, feel free to contact us here, or directly to the Support team at support@microblink.com.
