@valifysolutions/crossplatform-reactnative-vidvdockit

React Native bridge for VIDV DocKit (Valify document capture + OCR).

| Platform | Native SDK | |----------|------------| | iOS | VIDVDocKit ~> 1.7.0 | | Android | com.vidv:vidvdockitsdk:2.0.0 |

Both platforms return the same Promise response shape, including OCR extras inside result.extractedData.

Installation

npm install @valifysolutions/crossplatform-reactnative-vidvdockit
# or
yarn add @valifysolutions/crossplatform-reactnative-vidvdockit

iOS

Add the Valify CocoaPods source (if not already present), then install pods:

# Podfile
source 'https://github.com/CocoaPods/Specs.git'
# Valify private / Artifactory specs as required by your environment

cd ios && pod install

Android

The plugin already points at Valify Artifactory. Ensure the host app can resolve:

https://www.valifystage.com/artifactory/libs-release/

Rebuild the native app after installing (not Expo Go).

Quick start

import { startDocKit, type DocKitResponse } from '@valifysolutions/crossplatform-reactnative-vidvdockit';

async function openDocKit() {
  const response: DocKitResponse = await startDocKit({
    base_url: 'https://your-api.example.com/',
    access_token: '<token>',
    bundle_key: '<bundle-key>',
    document_type: 'egyNID',
    language: 'en',
    capture_mode: 'automatic',
    review_data: true,
    extras: ['advanced_confidence', 'document_verification_plus'],
    headers: {
      'X-Valify-reference-userid': 'user-123',
    },
  });

  switch (response.state) {
    case 'SUCCESS':
      console.log(response.result?.sessionID);
      console.log(response.result?.extractedData?.result);
      console.log(response.result?.extractedData?.advanced_confidence);
      break;
    case 'FAILURE':
      console.warn(response.code, response.message, response.result);
      break;
    case 'EXIT':
      console.log('User exited at', response.step);
      break;
    case 'ERROR':
      console.error('Builder error', response.code, response.message);
      break;
  }
}

Configuration (DocKitConfig)

Required

| Key | Type | Description | |-----|------|-------------| | base_url | string | Backend base URL | | access_token | string | Auth access token | | bundle_key | string | Bundle / license key | | document_type | DocumentType | See below |

Document types

| Value | Document | |-------|----------| | egyNID | Egyptian national ID | | tunNID | Tunisian national ID | | dzaNID | Algerian national ID | | passport | Passport (MRZ / OCR) | | ePassport | ePassport (NFC) |

Optional builder options

| Key | Type | Default | Notes | |-----|------|---------|-------| | language | 'en' \| 'ar' \| 'fr' | 'en' | Invalid values fall back to en on native | | review_data | boolean | true | Show OCR review screen | | collect_user_info | boolean | false | | | preview_captured_image | boolean | false | | | capture_mode | 'automatic' \| 'manual' \| 'auto_after' \| 'manual_after' | automatic | Preferred over manual_capture | | capture_mode_seconds | number | 10 | Used with auto_after / manual_after | | manual_capture | boolean | false | Deprecated — maps to capture_mode: 'manual' | | capture_only_mode | boolean | false | Skip OCR; return captures only | | epassport_security_config | boolean | SDK default | NFC security config for ePassport | | primary_color | string | SDK default | Hex, e.g. #62CBC9 | | headers | Record<string, string> | {} | e.g. reference user id | | ssl_certificate | string | — | Base64 certificate (both platforms) | | custom_logo | string | — | Base64 image | | disable_logo | boolean | false | | | extras | string[] | Record<string, boolean> | — | OCR extras (same on iOS & Android) | | manual_capture_validation | boolean | false | Android only | | document_validation | DocumentValidationRuleConfig[] | — | Android only |

Extras

Pass either an array of enabled keys or a boolean map:

extras: ['advanced_confidence', 'document_verification_plus', 'document_liveness']

// equivalent
extras: {
  advanced_confidence: true,
  document_verification_plus: true,
  document_liveness: true,
}

Common keys: advanced_confidence, document_verification_plus, document_liveness, profession_analysis, data_validation.

Requested extras appear as sibling keys next to result inside extractedData (not a separate top-level field).

Android-only: document validation

document_validation: [
  { path: 'document_verification_plus.expired', op: 'IS_FALSE' },
  { path: 'advanced_confidence.fraud_detection_zone', op: 'LESS_THAN', value: 50 },
  { path: 'result.front_nid', op: 'MATCH', match_path: 'result.back_nid' },
]

On rule failure the user can exit with state: 'FAILURE', code: 7018, and result.validationFailures.

Response handling

See docs/RESPONSE_HANDLING.md for the full unified contract, extras layout, capture keys, and error codes.

Summary:

| state | Meaning | Extra fields | |---------|---------|--------------| | SUCCESS | Flow completed | result | | FAILURE | Service / validation failure | code, message, result | | EXIT | User left the flow | step, result | | ERROR | Invalid builder config | code, message |

Permissions

Configure camera (and NFC for ePassport) in the host app:

• iOS — NSCameraUsageDescription (and NFC entitlements when using ePassport)
• Android — CAMERA (and location only if required by your backend / SDK policy)

Native SDK versions

Pinned in this plugin:

• iOS: CrossplatformReactnativeVidvdockit.podspec → VIDVDocKit ~> 1.7.0
• Android: android/build.gradle → com.vidv:vidvdockitsdk:2.0.0

Contributing

See CONTRIBUTING.md.

License

MIT