@onfido/react-native-sdk

Table of contents

• 1. Overview
• 2. Adding the SDK dependency
• 3. Initializing the SDK
• 4. Completing a session
• Advanced flow customization
• Advanced callbacks
• Custom media callbacks
• More information
• Raising support issues

Overview

The Onfido Smart Capture SDKs provide a set of screens and functionalities that enable applications to implement user identity verification flows. Each SDK contains:

• Carefully designed UX to guide your customers through the different photo or video capture processes
• Modular design to help you seamlessly integrate the different photo or video capture processes into your application's flow
• Advanced image quality detection technology to ensure the quality of the captured images meets the requirement of the Onfido identity verification process, guaranteeing the best success rate
• Direct image upload to the Onfido service, to simplify integration
• A suite of advanced fraud detection signals to protect against malicious users

All Onfido Smart Capture SDKs are orchestrated using Onfido Studio workflows, with only minor customization differences between the available platforms.

Environments and testing with the SDK

Two environments exist to support the Onfido SDK integrations:

• 'sandbox' - to be used for testing with sample documents
• 'live' - to be used only with real documents and in production apps

The environment being used is determined by the API token that is used to generate the necessary SDK token.

Going Live

Once you are satisfied with your integration and are ready to go live, please contact Customer Support to obtain a live API token. You will have to replace the sandbox token in your code with the live token.

Check that you have entered correct billing details inside your Onfido Dashboard, before going live.

Adding the SDK dependency

The React Native SDK supports:

• React Native 0.72
• iOS 12+
• Xcode 15+
• Android API level 21+
• iPads and tablets

Adding the Onfido React Native SDK to your project

This SDK supports React Native versions 0.72

If you are starting from scratch, you can follow the React Native CLI Quickstart. Once you have installed the React Native tools, you can run:

$ npx react-native init YourProjectName

You cannot use this SDK with Expo. If your project already uses Expo, you will need to follow the eject process, documented here.

Note: You will need to download and install Android Studio, configured as specified in the react-native guide for Android to run on an Android emulator.

Adding SDK dependency through npm

Navigate to the root directory of your React Native project. The rest of this section will assume you are in the root directory. Run the following command:

$ npm install @onfido/react-native-sdk --save

Update your Android build.gradle files

Update your build.grade files to reference the Android SDK, and enable multi-dex. If you build your project using the react-native init, with a build.gradle in the android/ and android/app/ directories, you can run this script to do it:

$ npm --prefix node_modules/@onfido/react-native-sdk/ run updateBuildGradle

allprojects {
  repositories {
    mavenCentral()
  }
}

android {
  defaultConfig {
     multiDexEnabled true
  }
}

Custom Android Application Class

Note: You can skip this step if you don't have any custom application class.

After the release of version 9.0.0, the Onfido React Native SDK runs in a separate process (for Android only). This means that when the Onfido SDK starts, a new application instance will be created. To prevent re-executing the initializations you have in the Android application class, you can use the isOnfidoProcess extension function and return from onCreate as shown below.

This will prevent initialization-related crashes such as: FirebaseApp is not initialized in this process

Kotlin

class YourCustomApplication : MultiDexApplication() {
	override fun onCreate() {
	    super.onCreate()
	    if (isOnfidoProcess()) {
	        return
	    }
	    
	    // Your custom initialization calls ...
	 }

  private fun isOnfidoProcess(): Boolean {
    val pid = Process.myPid()
    val manager = this.getSystemService(ACTIVITY_SERVICE) as ActivityManager

    return manager.runningAppProcesses.any {
        it.pid == pid && it.processName.endsWith(":onfido_process")
    }
  }
}

Update your iOS configuration files

Change ios/Podfile to use version 13:

platform :ios, '13.4'

Add descriptions for camera and microphone permissions to ios/YourProjectName/Info.plist:

  
	NSCameraUsageDescription
	Required for document and facial capture
	NSMicrophoneUsageDescription
	Required for video capture
  

Open Xcode and create an empty Swift file in your project root. For example, if your project is called YourProjectName, you can open it from the command line:

open ios/YourProjectName.xcodeproj

Once Xcode is open, add an empty Swift file: File > New File > Swift > Next > "SwiftVersion" > Create > Don't create Header. This will update your iOS configuration with a Swift version. All changes are automatically saved, so you can close Xcode.

Install the pods:

cd ios
pod install
cd ..

NFC capture using Onfido Studio

Recent passports, national identity cards and residence permits contain a chip that can be accessed using Near Field Communication (NFC). The Onfido SDKs provide a set of screens and functionalities to extract this information, verify its authenticity and provide the resulting verification as part of a Document report.

From version 10.0.0 onwards, NFC is enabled by default in the Onfido React Native SDK for Android and iOS and offered to customers when both the document and the device support NFC.

For more information on how to configure NFC and the list of supported documents, please refer to the NFC for Document Report guide.

Enabling NFC extraction for iOS

For iOS, the NFC feature requires Near Field Communication Tag Reading capability in your app target. If you haven't added it before, please follow the steps in Apple's documentation.

You're required to have the following key in your application's Info.plist file:

NFCReaderUsageDescription
Required to read ePassports

You have to include the entries below in your app target's Info.plist file to be able to read NFC tags properly:

com.apple.developer.nfc.readersession.felica.systemcodes

  12FC

com.apple.developer.nfc.readersession.iso7816.select-identifiers

  A0000002471001
  A0000002472001
  00000000000000
  D2760000850101

Disabling NFC and excluding dependencies

NFC is enabled by default. To disable NFC, include the nfcOption parameter with OnfidoNFCOptions.DISABLED while configuring the Onfido.start function:

config = {
  sdkToken: "",
  workflowRunId: "",
  nfcOption: OnfidoNFCOptions.DISABLED
}

For Android, a range of NFC library dependencies are included in the build automatically. In addition to configuring the nfcOption parameter, you must remove any libraries from the build process.

Exclude dependencies required for NFC from your build:

dependencies {
  implementation 'com.onfido.sdk.capture:onfido-capture-sdk:x.y.z' {
    exclude group: 'net.sf.scuba', module: 'scuba-sc-android'
    exclude group: 'org.jmrtd', module: 'jmrtd'
    exclude group: 'com.madgag.spongycastle', module: 'prov'
  }
}

If your application already uses the same libraries that the Onfido SDK needs for the NFC feature, you may encounter some dependency conflicts that will impact and could interfere with the NFC capture in our SDK. In such cases, we propose using the dependency resolution strategy below, by adding the following lines to your build.gradle file:

implementation ("com.onfido.sdk:onfido-:19.1.0"){
     exclude group: "org.bouncycastle"
 }
 implementation ("the other library that conflicts with Onfido on BouncyCastle") {
     exclude group: "org.bouncycastle"
 }
 
 implementation "org.bouncycastle:bcprov-jdk15to18:1.69"
 implementation "org.bouncycastle:bcutil-jdk15to18:1.69"

NFC Options

To configure NFC, include the nfcOption parameter with the three options below while configuring the Onfido.start function:

• DISABLED: NFC reading will not be asked of end-users
• OPTIONAL (Default): NFC reading will be attempted, if possible
• REQUIRED: NFC reading will be enforced, preventing end-users from completing the flow without a successful reading

Initializing the SDK

> ⚠️ The following SDK initialization documentation applies to identity verification workflows orchestrated using Onfido Studio. > For integrations where the verification steps are manually defined and configured, please refer to the Advanced flow customization section below.

The Reach Native SDK has multiple initialization and customization options that provide flexibility to your integration, while remaining easy to integrate.

Defining a workflow

Onfido Studio is the platform used to create highly reusable identity verification workflows for use with the Onfido SDKs. For an introduction to working with workflows, please refer to our Getting Started guide, or the Onfido Studio product guide.

SDK sessions are orchestrated by a session-specific workflow_run_id, itself derived from a workflow_id, the unique identifier of a given workflow.

For details on how to generate a workflow_run_id, please refer to the POST /workflow_runs/ endpoint definition in the Onfido API reference.

> Note that in the context of the SDK, the workflow_run_id property is referred to as workflowRunId.

Applicant ID reuse

When defining workflows and creating identity verifications, we highly recommend saving the applicant_id against a specific user for potential reuse. This helps to keep track of users should you wish to run multiple identity verifications on the same individual, or in scenarios where a user returns to and resumes a verification flow.

SDK authentication

The SDK is authenticated using SDK tokens. Onfido Studio generates and exposes SDK tokens in the workflow run payload returned by the API when a workflow run is created.

SDK tokens for Studio can only be used together with the specific workflow run they are generated for, and remain valid for a period of five weeks.

Note: You must never use API tokens in the frontend of your application as malicious users could discover them in your source code. You should only use them on your server.

Build a configuration object

To use the SDK, you need to obtain an instance of the client object, using your generated SDK token and workflow run ID.

config = {
  sdkToken: "",
  workflowRunId: ""
}

Start the flow

You can then launch the app with a call to Onfido.start.

Onfido.start(config);
// listen for the result

An expanded example of a configuration can be found below:

import React, {Component} from 'react';
import {Button, View} from 'react-native';
import {
  Onfido,
  OnfidoCaptureType,
  OnfidoCountryCode,
  OnfidoDocumentType,
} from '@onfido/react-native-sdk';

export default class App extends Component {
  startSDK() {
    Onfido.start({
      sdkToken: "",
      workflowRunId: "",
    })
      .then(res => console.warn('OnfidoSDK: Success:', JSON.stringify(res)))
      .catch(err => console.warn('OnfidoSDK: Error:', err.code, err.message));
  }

  render() {
    return (