@socure-inc/docv-react-native

v5.2.8

Published

13 days ago

The Predictive Document Verification (DocV) SDK React Native bridge allows you to use the DocV SDK v5 for Android and iOS in your React Native application.

0High
0Medium
0Low

react-native ios android socure socure-docv document-verification

Predictive DocV SDK v5 React Native

The Predictive Document Verification (DocV) SDK for React Native is a React Native wrapper that allows you to use the DocV SDK for Android or iOS in your React Native application.

Note: The Digital Intelligence SDK is required for all DocV iOS and Android SDK v5 integrations. For more information, see the Digital Intelligence SDK Guides in DevHub.

React Native New Architecture Support

Starting with this version 5.2.8, the wrapper fully supports the React Native New Architecture (TurboModules / Fabric) introduced in React Native 0.79+. Both Old Architecture and New Architecture builds are supported from the same package with no configuration changes required.

What changed

| Area | Old Architecture | New Architecture | |---|---|---| | Module system | NativeModules bridge | TurboModule (JSI, CodeGen spec) | | iOS bridge file | .m (ObjC extern) | .mm (conditional #ifdef RCT_NEW_ARCH_ENABLED) | | Android package | ReactPackage | BaseReactPackage with ReactModuleInfoProvider | | Peer dependencies | React ≥ 16.13.1, RN ≥ 0.66 | React ≥ 19.0.0, RN ≥ 0.79.0 |

New Promise-based API

In addition to the existing callback-based launchSocureDocV, a new Promise-based API launchSocureDocVWithPromise is now available. This is the recommended API for New Architecture apps and any new integrations.

import { launchSocureDocVWithPromise } from "@socure-inc/docv-react-native";

Under the New Architecture, launchSocureDocV also continues to work — it internally bridges callbacks over the TurboModule promise API when the legacy callback method is not available, so existing integrations require no code changes.

Enhanced error object

The onError callback now includes a machine-readable code field alongside the existing error message string. See the updated error reference for all codes.

Getting started

Before you begin, ensure you have the following:

Get a valid ID+ key from Admin Dashboard to authenticate API requests.
Get a valid SDK key from Admin Dashboard to initialize and authenticate the DocV SDK.
Add your IP address to the allowlist in Admin Dashboard.

React Native

React Native CLI. See the React Native docs for instructions on how to set up your development environment.
React Native 0.79.0 or later (required for New Architecture / TurboModule support)
React 19.0.0 or later

iOS

Xcode version 14.1+
Support for iOS 13 and later

Android

compileSdkVersion: 36
minSdkVersion: 23
Java: 17

Step 1: Install the React Native wrapper

In your React Native project, install the DocV React Native wrapper by running the following NPM command:

npm install @socure-inc/docv-react-native

Step 2: Configure your iOS or Android app

Your React Native project needs to access the DocV iOS or Android SDKs through the React Native wrapper. Follow the instructions in the dropdown menus below to integrate the DocV SDK into your iOS or Android app.

For the iOS app, you can install the DocV iOS SDK into your project using Cocoapods. If you do not already have the CocoaPods tool installed, see the CocoaPods Getting Started guide.

Add project dependencies

In your root project folder, open your Podfile with a text editor.
Specify the following project dependencies:
- Replace the deployment target with platform :ios, '13.0'.
- Add the following line:

pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'

Once completed, your Podfile should look like the following example:

# Resolve react_native_pods.rb with node to allow for hoisting
require Pod::Executable.execute_command('node', ['-p',
  'require.resolve(
    "react-native/scripts/react_native_pods.rb",
    {paths: [process.argv[1]]},
  )', __dir__]).strip

platform :ios, min_ios_version_supported
prepare_react_native_project!

linkage = ENV['USE_FRAMEWORKS']
if linkage != nil
  Pod::UI.puts "Configuring Pod with #{linkage}ally linked Frameworks".green
  use_frameworks! :linkage => linkage.to_sym
end

target 'DocVReactNativeSample' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    # An absolute path to your application root.
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  post_install do |installer|
    # https://github.com/facebook/react-native/blob/main/packages/react-native/scripts/react_native_pods.rb#L197-L202
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false,
      # :ccache_enabled => true
    )

    # fmt fails under Xcode 26 Clang (consteval FMT_STRING). base.h redefines
    # FMT_USE_CONSTEVAL unconditionally, so patch it to honor an external value,
    # then force it off below. Toolchain workaround; idempotent.
    fmt_base = File.join(installer.sandbox.root, 'fmt', 'include', 'fmt', 'base.h')
    if File.exist?(fmt_base)
      src = File.read(fmt_base)
      # Turn the chain's opening `#if` into an `#elif` behind our own branch.
      original_open = "#if !defined(__cpp_lib_is_constant_evaluated)\n#  define FMT_USE_CONSTEVAL 0\n"
      patched_open  = "#if defined(FMT_USE_CONSTEVAL)\n// honor externally-provided value\n" \
                      "#elif !defined(__cpp_lib_is_constant_evaluated)\n#  define FMT_USE_CONSTEVAL 0\n"
      if src.include?(original_open)
        src = src.sub(original_open, patched_open)
        File.chmod(0644, fmt_base)  # pod headers are read-only
        File.write(fmt_base, src)
        Pod::UI.puts "[fmt] Patched base.h to honor pre-set FMT_USE_CONSTEVAL".green
      end
    end

    # socure-docv-react-native (Swift + Obj-C++ static module) build fixes for
    # Xcode 26 / new arch. Patch the copied pod sources; idempotent.
    socure_ios = File.expand_path('../node_modules/@socure-inc/docv-react-native/ios', __dir__)

    # Fix 1: drop the non-modular C++ import from the bridging header — it breaks
    # Clang module scanning ("could not build module 'socure_docv_react_native'").
    bridging = File.join(socure_ios, 'SocureDocVReactNative-Bridging-Header.h')
    if File.exist?(bridging)
      original = File.read(bridging)
      patched = original.gsub(/^#import <ReactCommon\/RCTTurboModule\.h>\r?\n/, '')
      if patched != original
        File.chmod(0644, bridging)
        File.write(bridging, patched)
        Pod::UI.puts "[socure-docv] Removed non-modular C++ import from bridging header".green
      end
    end

    # Fix 2: promote SocureDocVHelper + its @objc methods to public, else the .mm
    # can't see them ("use of undeclared identifier 'SocureDocVHelper'").
    swift = File.join(socure_ios, 'SocureDocVReactNative.swift')
    if File.exist?(swift)
      original = File.read(swift)
      patched = original
        .gsub(/^class SocureDocVHelper\b/, 'public class SocureDocVHelper')
        .gsub(/^(\s*)@objc static func launch\b/, '\1@objc public static func launch')
      if patched != original
        File.chmod(0644, swift)
        File.write(swift, patched)
        Pod::UI.puts "[socure-docv] Promoted SocureDocVHelper to public for Obj-C interop".green
      end
    end

    # Fix 3: provide the module-named header swiftc self-imports; CocoaPods only
    # makes the dashed `...-umbrella.h`, so point a shim at it.
    public_headers = File.join(installer.sandbox.root, 'Headers', 'Public', 'socure_docv_react_native')
    if Dir.exist?(public_headers)
      shim = File.join(public_headers, 'socure_docv_react_native.h')
      shim_body = "#import \"socure-docv-react-native-umbrella.h\"\n"
      if !File.exist?(shim) || File.read(shim) != shim_body
        File.write(shim, shim_body)
        Pod::UI.puts "[socure-docv] Added module-named umbrella shim header".green
      end
    end

    installer.pods_project.targets.each do |t|
      if ['fmt', 'glog'].include?(t.name)
        t.build_configurations.each do |c|
          defs = c.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] || ['$(inherited)']
          defs = [defs] unless defs.is_a?(Array)
          defs.delete('FMT_USE_NONTYPE_TEMPLATE_ARGS=0')
          defs.delete('FMT_CONSTEVAL=')
          defs << 'FMT_USE_CONSTEVAL=0' unless defs.include?('FMT_USE_CONSTEVAL=0')
          c.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] = defs
        end
      end
    end
  end

  pod 'socure-docv-react-native', :path => '../node_modules/@socure-inc/docv-react-native'
end

Install the dependencies

Go to the ios folder in your project:

cd ios

Install the Cocoapods dependencies by running the following command:

pod install

Use the CocoaPods-generated `.xcworkspace` file

The pod install command generates a .xcworkspace file with all the configured dependencies. To continue with the installation, complete the following:

Close Xcode if it's already open.
Use the .xcworkspace file reopen your project in Xcode.
Check that your deployment target is set to iOS 13.0 or later.

Request camera permissions

The DocV iOS SDK requires a device's camera permission to capture identity documents. Upon the first invocation of the SDK, the app will request camera permission from the consumer. If the app does not already use the camera, you must add the following to the app’s Info.plist file:

| Key | Type | Value | |------------------------------------|--------|---------------------------------------------------------------------------------------------| | Privacy - Camera Usage Description | String | "This application requires use of your camera in order to capture your identity documents." |

Note: We recommend you check for camera permission before calling the SocureDocV SDK’s launch API.

For the Android app, add your project dependencies by going to the module level build.gradle file and making sure the minSdkVersion is set to at least 23 and the compileSdkVersion is set to at least 36.

buildscript {
              .....
            ext {
                 ....
                minSdkVersion = 23 
                compileSdkVersion = 36
                .....
            }
}

Camera and file permissions

The DocV SDK requires camera and file permission to capture identity documents. Upon the first invocation of the SDK, your app will request camera and file permission from the consumer.

Note: We recommend you check for camera and file permissions before calling the Socure DocV SDK’s launch API.

Ensure that your app manifest has been set up properly to request the following required permissions:

<uses-feature android:name="android.hardware.camera" />

<!-- Declare permissions -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Step 3: Run the app

Return to your root project folder in the command line.

For the DocV iOS SDK, enter the following command to run the app:

react-native run-ios

For the DocV Android SDK, enter the following command to run the app:

react-native run-android

Step 4: Generate a transaction token and configure the Capture App

To initiate the verification process, generate a transaction token (docvTransactionToken) by calling the Document Request endpoint v5. We strongly recommend that customers generate this token via a server-to-server API call and then pass it to the DocV SDK to ensure the security of their API key and any data they send to Socure.

Call the Document Request endpoint

From your backend, make a POST request to the /documents/request endpoint specifying the following information in the config object:

| Parameter | Required | Description | |------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | language | Optional | Determines the language package for the UI text on the Capture App. Possible values are: - Arabic: ar - Armenian: hy - Bengali: bn - Brazilian Portuguese: pt-br - Chinese (Simplified): zh-cn - Chinese (Traditional): zh-tw - English: en - French: fr - Haitian Creole: ht - Italian: it - Korean: ko - Polish: pl-PL - Russian: ru - Spanish (EU): es - Tagalog: tl - Urdu: ur - Vietnamese: vi Note: Socure can quickly add support for new language requirements. For more information, contact [email protected]. | | useCaseKey | Optional | Deploys a customized Capture App flow on a per-transaction basis. Replace the customer_use_case_key value with the name of the flow you created in Admin Dashboard. - If this field is empty, the Capture App will use the flow marked as Default in Admin Dashboard. - If the value provided is incorrect, the SDK will return an Invalid Request error. |

Note: We recommend including as much consumer PII in the body of the request as possible to return the most accurate results.

curl --location 'https://service.socure.com/api/5.0/documents/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: SocureApiKey a182150a-363a-4f4a-xxxx-xxxxxxxxxxxx' \
--data '{
  "config": {
    "useCaseKey": "customer_use_case_key", 
    ...
  }
  "firstName": "Dwayne",
  "surName": "Denver",
  "dob": "1975-04-02",
  "mobileNumber": "+13475550100",
  "physicalAddress": "200 Key Square St",
  "physicalAddress2": null,
  "city": "Brownsville",
  "state": "TN",
  "zip": "38012",
  "country": "US"
}'

When you receive the API response, collect the docvTransactionToken. This value is required to initialize the DocV Android SDK and fetch the DocV results.

{
  "referenceId": "123ab45d-2e34-46f3-8d17-6f540ae90303",
    "data": {
      "eventId": "acdf5b1a-c96b-4ed8-92b9-59471397d04a",
      "customerUserId": "121212",
      "docvTransactionToken" : "acdf5b1a-c96b-4ed8-92b9-59471397d04a", 
      "qrCode": "data:image/png;base64,iVBO......K5CYII=",
      "url": "https://verify.socure.com/#/dv/acdf5b1a-c96b-4ed8-92b9-59471397d04a"
    }
}

Step 5: Import and launch the SDK

The wrapper exposes two APIs. Use launchSocureDocVWithPromise for new integrations and any app running React Native 0.79+. Use launchSocureDocV if your codebase already uses callbacks or you need to support older React Native versions.

Option A: Promise-based API (recommended)

The Promise-based API is the recommended approach for New Architecture apps. It uses async/await and standard JavaScript error handling.

Import launchSocureDocVWithPromise:

import { launchSocureDocVWithPromise } from "@socure-inc/docv-react-native";

Call launchSocureDocVWithPromise inside an async function:

try {
  const result = await launchSocureDocVWithPromise(
    "docVTransactionToken",
    "SOCURE_SDK_KEY",
    false // useSocureGov
  );
  console.log("Success:", result.deviceSessionToken);
} catch (error) {
  console.log("Error code:", error.code);
  console.log("Error message:", error.message);
}

`launchSocureDocVWithPromise` Parameters

| Parameter | Type | Description | |---|---|---| | docVTransactionToken | String | The transaction token from the /documents/request API response. Required to initiate the document verification session. | | publicKey | String | The unique SDK key from Admin Dashboard used to authenticate the SDK. | | useSocureGov | Boolean | Set to true to use the GovCloud environment. Defaults to false. Applicable only to customers provisioned in the SocureGov environment. |

Returns: Promise<DocVResult> — resolves with { deviceSessionToken: string } on success, or rejects with an error object containing code and message on failure.

Option B: Callback-based API (legacy)

The callback-based API is preserved for backward compatibility. Existing integrations do not require any code changes.

Import launchSocureDocV:

import { launchSocureDocV } from "@socure-inc/docv-react-native";

Call launchSocureDocV to initiate the Socure DocV SDK:

launchSocureDocV(
  "docVTransactionToken",
  "SOCURE_SDK_KEY",
  false, // useSocureGov
  onSuccess,
  onError
);

`launchSocureDocV` Parameters

New Architecture note: Under React Native New Architecture, launchSocureDocV automatically routes through the TurboModule promise API and bridges the result back to your onSuccess / onError callbacks. No code changes are required.

Step 6: Handle response callbacks

Success response

When the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers, the SDK returns a DocVResult object containing a device session token.

Promise API — the Promise resolves with:

{
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
}

Callback API — the onSuccess callback receives the same object:

{
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
}

The deviceSessionToken can be used to access device risk details for the specific session.

`onError` response

The onError callback (and Promise rejection) is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it.

Promise API — the Promise rejects with a JavaScript Error-like object. Access error.code and error.message:

try {
  const result = await launchSocureDocVWithPromise(token, key, false);
} catch (error) {
  console.log(error.code);    // e.g. "ERR_USER_CANCELED"
  console.log(error.message); // e.g. "Scan canceled by the user"
}

Callback API — the onError callback receives an object with the following shape:

{
  code: 'ERR_USER_CANCELED',
  error: 'Scan canceled by the user',
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...'
}

Migration note: The error field (human-readable message string) is preserved from previous versions. The new code field (machine-readable constant) was added in this release to enable reliable programmatic error handling without string matching.

Error reference

The following errors may be returned by the Socure DocV SDK:

| code | error message | Description | |---|---|---| | ERR_NO_INTERNET | "No internet connection" | Device has no network connectivity. | | ERR_SESSION_INITIATION | "Failed to initiate the session" | The SDK could not start a verification session with Socure servers. | | ERR_CAMERA_PERMISSION | "Permissions to open the camera declined by the user" | The user denied camera access. | | ERR_CONSENT_DECLINED | "Consent declined by the user" | The user declined the consent screen. | | ERR_UPLOAD_FAILURE | "Failed to upload the documents" | Captured images could not be uploaded. | | ERR_INVALID_TOKEN | "Invalid transaction token" | The docVTransactionToken is missing, malformed, or already used. | | ERR_INVALID_KEY | "Invalid or missing SDK key" | The publicKey (SDK key) is invalid or was not provided. | | ERR_SESSION_EXPIRED | "Session expired" | The verification session timed out before completion. | | ERR_USER_CANCELED | "Scan canceled by the user" | The user dismissed the capture flow before completing it. | | ERR_NO_ACTIVITY | "App activity is null" | Android only — the host Activity was not available when the SDK attempted to launch. | | ERR_NO_DATA | "No result data returned from SDK" | Android only — the SDK activity returned without data. | | ERR_NO_VIEW_CONTROLLER | "Failed to get root view controller" | iOS only — the root UIViewController could not be resolved. | | ERR_ALREADY_IN_PROGRESS | "A DocV session is already in progress" | A previous call has not yet resolved. Wait for it to complete before launching again. | | ERR_UNKNOWN | "Unknown error" | An unrecognized error occurred. |

Step 7: Fetch the verification results

When the consumer successfully completes the document capture and upload process, call the ID+ endpoint fetch the results. See the API Reference documentation on DevHub for more information.