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.

Table of Contents

1. Getting Started
2. Step 1: Install the React Native Wrapper
3. Step 2: Configure Your iOS or Android App
4. Step 3: Run the App
5. Step 4: Generate a Transaction Token and Configure the Capture App
6. Step 5: Import and Launch the SDK
7. Step 6: Handle Response Callbacks
8. Step 7: Fetch the Verification Results

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.

iOS

• Xcode version 14.1+
• Support for iOS 13 and later

Android

• compileSdkVersion: 34
• 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

1. In your root project folder, open your Podfile with a text editor.
2. 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:

require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'

platform :ios, '13.0'
install! 'cocoapods', :deterministic_uuids => false

production = ENV["PRODUCTION"] == "1"

target 'SocureDocVDemo' do
  config = use_native_modules!

  # Flags change depending on the env values.
  flags = get_default_flags()

  use_react_native!(
    :path => config[:reactNativePath],
    # to enable hermes on iOS, change `false` to `true` and then install pods
    :production => production,
    :hermes_enabled => flags[:hermes_enabled],
    :fabric_enabled => flags[:fabric_enabled],
    :flipper_configuration => FlipperConfiguration.enabled,
    # An absolute path to your application root.
    :app_path => "#{Pod::Config.instance.installation_root}/.."
  )

  target 'SocureDocVDemoTests' do
    inherit! :complete
    # Pods for testing
  end

  post_install do |installer|
    react_native_post_install(installer)
    __apply_Xcode_12_5_M1_post_install_workaround(installer)
  end

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

end

Install the dependencies

1. Go to the ios folder in your project:

cd ios

2. 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:

1. Close Xcode if it's already open.
2. Use the .xcworkspace file reopen your project in Xcode.
3. 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 22 and the compileSdkVersion is set to at least 32.

buildscript {
              .....
            ext {
                 ....
                minSdkVersion = 22 
                compileSdkVersion = 34
                .....
            }
}

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

1. 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

1. 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"
}'

2. 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

1. Add the following code to your App.js file to import launchSocureDocV:

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

2. Call launchSocureDocV to initiate the Socure DocV SDK:

launchSocureDocV("docVTransactionToken", "SOCURE_SDK_KEY", userSocureGov, onSuccess, onError);

launchSocureDocV Parameters

The following table lists the parameters for the launchSocureDocV function:

| Parameter | Type | Description | |--------------------------|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SOCURE_SDK_KEY | String | The unique SDK key obtained from Admin Dashboard used to authenticate the SDK. | | DocV_Transaction_Token | String | The transaction token retrieved from the API response of the /documents/request endpoint. Required to initiate the document verification session. | | useSocureGov | Bool | A Boolean flag indicating whether to use the GovCloud environment. It defaults to false. This is only applicable for customers provisioned in the SocureGov environment. | | onSuccess | Function | A callback function invoked when the flow completes successfully. | | onError | Function | A callback function invoked when the flow fails. |

Step 6: Handle response callbacks

Your app can receive response callbacks from the launchSocureDocV function when the flow either completes successfully or returns with an error. The SDK represents these outcomes using the onSuccess and onError callback functions.

onSuccess response

The onSuccess callback is triggered when the consumer successfully completes the verification flow and the captured images are uploaded to Socure's servers. It returns an object containing a device session token, which can be used for accessing device details about the specific session.

{ 
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA' 
}

onError response

The onError callback is triggered when the DocV SDK encounters an error or when the consumer exits the flow without completing it. It returns a message printed with the deviceSessionToken and specific error details.

{ 
  deviceSessionToken: 'eyJraWQiOiJmMzRiN2YiLCJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJzd3QiOiJmZWJlMDYxNS0wYjgxLTRkNTMtYjgyMS03YTAxNjUwZTFiMjEifQ.kz3W8oQxmlqWk1x3W4mf7BSgGmr-qAyvN6fxR_yusbfWdznYVAzdeabHdyW0vAFGgGYvEmyX-5YUtHDMQB0ptA',
  error: 'Scan canceled by the user' 
}

Possible onError messages

The following error messages may be returned by the Socure DocV SDK:

| Error Message | Error Description | |-------------------------------------------------------|-------------------------------------------------------------------| | "No internet connection" | No internet connection | | "Failed to initiate the session" | Failed to initiate the session | | "Permissions to open the camera declined by the user" | Permissions to open the camera declined by the user | | "Consent declined by the user" | Consent declined by the user | | "Failed to upload the documents" | Failed to upload the documents | | "Invalid transaction token" | Invalid transaction token | | "Invalid or missing SDK key" | Invalid or missing SDK key | | "Session expired" | Session expired | | "Scan canceled by the user" | Scan canceled by the user | | "Unknown error" | Unknown error |

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.