React Native IDM Scan SDK

A fully dynamic, production-ready React Native SDK for identity verification with document scanning, selfie capture, and API-driven configuration.

🌟 Features

• ✅ Fully Dynamic - All configuration driven by API and metadata
• ✅ Smart Document Flow - Automatically determines required capture steps
• ✅ 18 Verification Screens - Complete identity verification flow
• ✅ Document Scanning - Support for ID cards, passports, driver licenses
• ✅ Selfie Capture - Live selfie verification with camera integration
• ✅ MRZ & Barcode Scanning - Machine-readable zone and barcode support with Dynamsoft & ML Kit
• ✅ Advanced Scanning - Optional Dynamsoft barcode scanner and ML Kit text recognition
• ✅ 10 Pre-built Themes - Customizable UI themes
• ✅ Camera & Location Permissions - Built-in permission handling
• ✅ TypeScript Support - Full type definitions included
• ✅ Responsive Design - Works on all screen sizes
• ✅ Optimized Performance - Memoization and efficient state management

📱 Requirements

• React Native >= 0.64.0
• iOS >= 11.0
• Android >= API 21 (Android 5.0)
• Node.js >= 14.x

📦 Installation

Step 1: Install the SDK

npm install @test-web/react-native-sdk

or with Yarn:

yarn add @test-web/react-native-sdk

Step 2: Install Required Dependencies

npm install @react-navigation/native @react-navigation/native-stack
npm install react-native-screens react-native-safe-area-context
npm install react-native-vision-camera react-native-image-resizer react-native-fs

Step 3: Install Optional Dependencies (Recommended)

npm install react-native-device-info react-native-geolocation-service

Step 4: Install Scanning Libraries (Optional but Recommended)

For enhanced barcode and MRZ scanning capabilities:

# Dynamsoft Capture Vision for barcode scanning
npm install dynamsoft-capture-vision-react-native

# ML Kit for MRZ text recognition
npm install @react-native-ml-kit/text-recognition

Note: Without these libraries, the SDK will use fallback simulation for barcode and MRZ scanning. For production use, we strongly recommend installing these libraries for accurate scanning.

Step 5: Install iOS Pods (iOS only)

cd ios && pod install && cd ..

Step 6: Rebuild Your App

# For Android
npx react-native run-android

# For iOS
npx react-native run-ios

⚙️ Configuration

Android Setup

1. Add Permissions to AndroidManifest.xml

Open android/app/src/main/AndroidManifest.xml and add:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Camera Permission (Required) -->
    <uses-permission android:name="android.permission.CAMERA" />
    
    <!-- Location Permissions (Required) -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    
    <!-- Storage Permissions (Required for saving images) -->
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" 
                     android:maxSdkVersion="28" />
    
    <!-- Internet Permission (Required for API calls) -->
    <uses-permission android:name="android.permission.INTERNET" />
    
    <!-- Camera Features (Optional but recommended) -->
    <uses-feature android:name="android.hardware.camera" android:required="false" />
    <uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />

    <application>
        <!-- Your app configuration -->
    </application>

</manifest>

2. Update build.gradle

Ensure your android/app/build.gradle has minimum SDK version 21:

android {
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 33
    }
}

iOS Setup

1. Add Privacy Permissions to Info.plist

Open ios/YourAppName/Info.plist and add:

<key>NSCameraUsageDescription</key>
<string>We need camera access to scan your documents and capture selfie for identity verification</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location for identity verification purposes</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to your photo library to save captured images</string>

<key>NSPhotoLibraryAddUsageDescription</key>
<string>We need permission to save captured images to your photo library</string>

2. Update Podfile

Ensure your ios/Podfile has minimum iOS version 11.0:

platform :ios, '11.0'

Dynamsoft Barcode Scanner Setup (Optional)

If you installed dynamsoft-capture-vision-react-native, follow these additional steps:

Android Configuration

1. Add to android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 21
        // Add this for Dynamsoft
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}

2. Get your Dynamsoft license key from Dynamsoft Customer Portal

3. Initialize the license in your app (before using the SDK):

import { DCVBarcodeReader } from 'dynamsoft-capture-vision-react-native';

// Initialize Dynamsoft license (do this once at app startup)
await DCVBarcodeReader.initLicense('YOUR_DYNAMSOFT_LICENSE_KEY');

iOS Configuration

1. Add to ios/Podfile:

platform :ios, '11.0'

target 'YourApp' do
  # ... other pods
  
  # Add this for Dynamsoft
  pod 'DynamsoftCaptureVisionRouter', '~> 2.0'
  pod 'DynamsoftBarcodeReader', '~> 10.0'
end

2. Run pod install:

cd ios && pod install && cd ..

Note: The SDK will automatically detect if Dynamsoft is available and use it for barcode scanning. If not installed, it will fall back to simulation mode.

ML Kit Text Recognition Setup (Optional)

If you installed @react-native-ml-kit/text-recognition, follow these additional steps:

Android Configuration

ML Kit will be automatically configured on Android. No additional setup required.

iOS Configuration

1. Add to ios/Podfile:

platform :ios, '11.0'

target 'YourApp' do
  # ... other pods
  
  # ML Kit is automatically linked
end

2. Run pod install:

cd ios && pod install && cd ..

Note: The SDK will automatically detect if ML Kit is available and use it for MRZ text recognition. If not installed, it will fall back to simulation mode.

🚀 Usage

Basic Implementation

import React from 'react';
import { IDMScan } from '@test-web/react-native-sdk';

export default function App() {
  const config = {
    clientID: 'your-client-id',
    clientSecret: 'your-client-secret',
    environment: 'sandbox', // or 'production'
    requestData: {
      requestID: 'unique-request-id',
      name: 'John Doe',
      dateOfBirth: '1990-01-01',
    },
    theme: 'light',
  };

  return <IDMScan idmConf={config} />;
}

With Custom Configuration

import React from 'react';
import { IDMScan } from '@test-web/react-native-sdk';

export default function App() {
  const idmConfiguration = {
    clientID: process.env.IDM_CLIENT_ID,
    clientSecret: process.env.IDM_CLIENT_SECRET,
    environment: 'sandbox',
    requestData: {
      requestID: generateUniqueId(),
      name: 'John Doe',
      dateOfBirth: '1990-01-01',
      countryCode: 'US',
      mobile: '+1234567890',
      callbackURL: 'https://your-api.com/callback',
    },
    theme: 'ocean',
  };

  return <IDMScan idmConf={idmConfiguration} />;
}

🎨 Available Themes

The SDK comes with 10 pre-built themes:

| Theme Name | Usage | |------------|-------| | Light | theme: 'light' | | Dark | theme: 'dark' | | Ocean | theme: 'ocean' | | Sunset | theme: 'sunset' | | Forest | theme: 'forest' | | Pastel | theme: 'pastel' | | High Contrast | theme: 'highContrast' | | Professional | theme: 'professional' | | Sakura | theme: 'sakura' | | Midnight | theme: 'midnight' |

Custom Theme Example

import { IDMScan } from '@test-web/react-native-sdk';

const customTheme = {
  colors: {
    primary: '#FF6B6B',
    secondary: '#4ECDC4',
    background: '#FFFFFF',
    text: '#2C3E50',
    subtitle: '#7F8C8D',
    border: '#BDC3C7',
    error: '#E74C3C',
    success: '#2ECC71',
  },
  spacing: {
    xs: 4,
    sm: 8,
    md: 16,
    lg: 24,
    xl: 32,
  },
};

export default function App() {
  return <IDMScan idmConf={{ ...config, theme: customTheme }} />;
}

📸 Scanning Capabilities

Barcode Scanning

The SDK supports barcode scanning with two modes:

1. Production Mode (Recommended)

Install Dynamsoft Capture Vision for accurate barcode scanning:

npm install dynamsoft-capture-vision-react-native

Supported Barcode Types:

• PDF417 (Driver's License, ID Cards)
• QR Code
• Code 128
• Code 39
• EAN-13
• UPC-A
• And more...

Initialize License:

import { DCVBarcodeReader } from 'dynamsoft-capture-vision-react-native';

// At app startup
await DCVBarcodeReader.initLicense('YOUR_LICENSE_KEY');

Get your free trial license from Dynamsoft Customer Portal.

2. Fallback Mode

Without Dynamsoft installed, the SDK will use simulation mode for testing purposes. This is useful for development but not recommended for production.

MRZ Scanning

The SDK supports MRZ (Machine Readable Zone) scanning with two modes:

1. Production Mode (Recommended)

Install ML Kit Text Recognition for accurate MRZ scanning:

npm install @react-native-ml-kit/text-recognition

Supported MRZ Types:

• TD1 (ID Cards)
• TD2 (Travel Documents)
• TD3 (Passports)
• MRVA (Visa Type A)
• MRVB (Visa Type B)

The SDK automatically detects the MRZ type based on document metadata.

2. Fallback Mode

Without ML Kit installed, the SDK will use simulation mode for testing purposes. This is useful for development but not recommended for production.

Scanning Flow

The SDK automatically determines which scanning methods are required based on document metadata:

// Example metadata from API
{
  "document_flow": ["F", "B"],  // Front and Back required
  "barcode": "PDF417 B"          // Barcode on back side
}

Flow: Selfie → Front → Back → Barcode Scan → Complete

// Example metadata for passport
{
  "document_flow": ["F"],  // Front only
  "barcode": "TD3"         // MRZ scanning required
}

Flow: Selfie → Front → MRZ Scan → Complete

🔄 Dynamic Flow

The SDK automatically determines the verification flow based on document metadata:

Flow Examples

Example 1: Driver's License (Front Only)

{
  "document_flow": ["F"],
  "barcode": "None"
}

Flow: Selfie → Front Document → Complete

Example 2: Passport (Front + MRZ)

{
  "document_flow": ["F"],
  "barcode": "TD3"
}

Flow: Selfie → Front Document → MRZ Scan → Complete

Example 3: National ID (Front + Back + Barcode)

{
  "document_flow": ["F", "B"],
  "barcode": "PDF417 B"
}

Flow: Selfie → Front Document → Back Document → Barcode Scan → Complete

📚 API Reference

IDMConf Interface

interface IDMConf {
  // Required
  clientID: string;
  clientSecret: string;
  environment: 'sandbox' | 'production';
  requestData: RequestData;

  // Optional
  theme?: 'light' | 'dark' | Theme;
  userDetails?: UserDetails;
  accessToken?: string;
  verificationCode?: string;
  configuration?: Configuration;
  countryDetails?: CountryDetail[];
  selectedCountryDetails?: SelectedCountryDetail;
  requestConfiguration?: RequestConfiguration;
}

interface RequestData {
  requestID: string;
  name?: string;
  dateOfBirth?: string;
  countryCode?: string;
  mobile?: string;
  callbackURL?: string;
  redirectURL?: string;
}

Exported Components

import {
  IDMScan,           // Main SDK component
  Button,            // Themed button component
  ThemedText,        // Themed text component
  Loader,            // Loading indicator
  Header,            // Header component
  Footer,            // Footer component
  CustomOverlay,     // Overlay component
} from '@test-web/react-native-sdk';

Exported Hooks

import {
  useTheme,          // Access current theme
  useOrientation,    // Detect device orientation
  useKeyboard,       // Keyboard visibility state
  useIDM,            // Access IDM configuration
} from '@test-web/react-native-sdk';

Exported Utilities

import {
  debounce,                    // Debounce function calls
  throttle,                    // Throttle function calls
  memoize,                     // Memoize function results
  base64Encode,                // Encode to base64
  base64Decode,                // Decode from base64
  getDocumentLabel,            // Get document type label
  FlowManager,                 // Flow management class
  createFlowManager,           // Create flow manager
  processImageToBase64,        // Process images
} from '@test-web/react-native-sdk';

API Services

import { ScanServices } from '@test-web/react-native-sdk';

// Available APIs
ScanServices.getUserDataAPI();
ScanServices.generateAccessToken(config);
ScanServices.generateRequest(config, requestData);
ScanServices.getConfiguration(config, verificationCode);
ScanServices.getCountries(config);
ScanServices.captureDocumentFront(config, photoData);
ScanServices.captureDocumentBack(config, photoData);
ScanServices.captureBarcode(config, barcodeData);
ScanServices.captureMRZ(config, mrzData);
ScanServices.completeVerification(config);

🔧 Troubleshooting

Common Issues

1. Camera Permission Denied

Problem: Camera not working or permission denied error.

Solution:

• Ensure you've added camera permissions to AndroidManifest.xml (Android)
• Ensure you've added NSCameraUsageDescription to Info.plist (iOS)
• Request permissions at runtime before using the SDK

2. Location Not Available

Problem: Location permission errors.

Solution:

• Check location permissions in manifest/plist
• Ensure GPS is enabled on device
• Verify react-native-geolocation-service is installed

3. Navigation Error

Problem: Couldn't find a navigation object error.

Solution:

• Ensure all navigation dependencies are installed
• Run pod install for iOS
• Clean and rebuild the app

4. iOS Build Failed

Problem: Build fails on iOS after installation.

Solution:

cd ios && pod install && cd ..
# Clean build folder in Xcode
# Product → Clean Build Folder
# Rebuild the app

5. Android Build Failed

Problem: Build fails on Android with dependency errors.

Solution:

cd android && ./gradlew clean && cd ..
# Rebuild the app

6. Image Processing Fails

Problem: Images not uploading or processing errors.

Solution:

• Ensure react-native-image-resizer is installed
• Ensure react-native-fs is installed
• Check storage permissions

7. Barcode Scanning Not Working

Problem: Barcode scanning shows simulation or doesn't detect barcodes.

Solution:

• Install dynamsoft-capture-vision-react-native for real barcode scanning
• Initialize Dynamsoft license key before using the SDK
• Ensure camera permissions are granted
• Test with a real PDF417 barcode (driver's license back)
• Check console logs for Dynamsoft initialization errors

8. MRZ Scanning Not Working

Problem: MRZ scanning shows simulation or doesn't detect MRZ codes.

Solution:

• Install @react-native-ml-kit/text-recognition for real MRZ scanning
• Ensure camera permissions are granted
• Test with a real passport or ID card with MRZ
• Ensure good lighting and steady camera position
• Check console logs for ML Kit errors

🧪 Testing Scanning Features

Testing Barcode Scanning

With Dynamsoft (Production)

1. Install Dynamsoft:

npm install dynamsoft-capture-vision-react-native

2. Get a trial license from Dynamsoft

3. Initialize in your app:

import { DCVBarcodeReader } from 'dynamsoft-capture-vision-react-native';

await DCVBarcodeReader.initLicense('YOUR_LICENSE_KEY');

4. Test with a real driver's license or ID card with PDF417 barcode

Without Dynamsoft (Development)

The SDK will automatically use simulation mode. After 3 seconds, it will generate a simulated barcode result.

Testing MRZ Scanning

With ML Kit (Production)

1. Install ML Kit:

npm install @react-native-ml-kit/text-recognition

2. Test with a real passport or ID card with MRZ zone

3. Ensure good lighting and hold the document steady

Without ML Kit (Development)

The SDK will automatically use simulation mode. After 3 seconds, it will generate a simulated MRZ result.

Checking Scanner Status

The SDK logs which scanning mode is being used:

// Console output examples:
"Dynamsoft Barcode Scanner initialized" // Production mode
"Dynamsoft not available, using fallback" // Simulation mode

"ML Kit text recognition initialized" // Production mode
"ML Kit not available, using fallback" // Simulation mode

🎯 Advanced Usage

Using Context

import { useIDM } from '@test-web/react-native-sdk';

function MyComponent() {
  const { idmConf, updateIDMConf } = useIDM();
  
  // Access configuration
  console.log(idmConf.verificationCode);
  
  // Update configuration
  updateIDMConf({ theme: 'dark' });
}

Flow Manager

import { createFlowManager } from '@test-web/react-native-sdk';

const metadata = idmConf.selectedCountryDetails?.selectedMetaData;
const flowManager = createFlowManager(metadata);

// Check requirements
const needsBack = flowManager.requiresBackCapture();
const needsBarcode = flowManager.requiresBarcodeCapture();
const needsMRZ = flowManager.requiresMRZCapture();

// Get next screen
const nextScreen = flowManager.getNextScreenAfterFront();

Image Processing

import { processImageToBase64 } from '@test-web/react-native-sdk';

const base64Image = await processImageToBase64(imagePath, {
  width: 810,
  height: 1080,
  quality: 70,
  format: 'JPEG',
});

📊 Performance

The SDK includes several performance optimizations:

• Memoization - Components and calculations are memoized
• Lazy Loading - Heavy dependencies loaded only when needed
• Image Optimization - Images resized before upload (810x1080, 70% quality)
• Efficient State - Minimal re-renders with optimized context
• API Caching - Countries and configuration cached after first fetch

🔒 Security

• OAuth2 authentication with client credentials
• Secure token management
• HTTPS for all API calls
• No sensitive data stored locally
• Proper error handling without exposing internals

📄 License

MIT License

Copyright (c) 2024 Your Company

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

📞 Support

• Email: [email protected]
• GitHub: https://github.com/yourcompany/react-native-sdk
• Documentation: https://docs.yourcompany.com

🎉 What's New in v2.0.0

Major Changes

• ✅ Fully Dynamic - All configuration driven by API
• ✅ Metadata-Driven Navigation - Automatic flow determination
• ✅ Real API Integration - All APIs implemented
• ✅ Enhanced Type System - Complete TypeScript coverage
• ✅ Performance Optimizations - Memoization and efficient rendering
• ✅ Image Processing - Automatic resize and compression
• ✅ Flow Manager - Smart navigation based on document type
• ✅ Better Error Handling - Comprehensive error management
• ✅ Loading States - User feedback throughout the flow
• ✅ Dynamsoft Integration - Professional barcode scanning (optional)
• ✅ ML Kit Integration - Accurate MRZ text recognition (optional)

Scanning Features

• Dynamsoft Capture Vision - Industry-leading barcode scanning for PDF417, QR codes, and more
• ML Kit Text Recognition - Google's ML Kit for accurate MRZ detection on passports and ID cards
• Fallback Mode - Simulation mode for development without external libraries
• Auto-Detection - SDK automatically uses available scanning libraries

Breaking Changes from v1.x

• clientID, clientSecret, environment, and requestData are now required
• Static country data removed (now fetched from API)
• Navigation flow is now metadata-driven

Migration from v1.x

See migration guide in the repository for detailed instructions.

Made with ❤️ by Your Company

Version: 2.0.0
Status: Production Ready
Last Updated: December 22, 2024