@onfido/react-native-sdk
Advanced tools
This SDK provides a drop-in set of screens and tools for react native applications to allow capturing of identity documents and face photos/live videos for the purpose of identity verification with Onfido. The SDK offers a number of benefits to help you create the best on-boarding/identity verification experience for your customers:
ℹ️
If you are integrating using Onfido Studio please see our Studio integration guide
* Note: The SDK is only responsible for capturing and uploading document photos, live selfies, live videos and motion captures. You still need to access the Onfido API to manage applicants and Onfido Studio to build verification workflows.
In order to start integration, you will need the API token. You can use our sandbox environment to test your integration, and you will find the API tokens inside your Onfido Dashboard. You can create API tokens inside your Onfido Dashboard as well.
You must create an Onfido applicant before you start the flow.
For a document or face check the minimum applicant details required are firstName and lastName.
You must create applicants from your server:
$ curl https://api.onfido.com/v3/applicants \
-H 'Authorization: Token token=YOUR_API_TOKEN' \
-d 'first_name=Theresa' \
-d 'last_name=May'
The JSON response has an id field containing a UUID that identifies the applicant. All documents or live photos/videos uploaded by that instance of the SDK will be associated with that applicant.
You will need to generate and include a short-lived JSON Web Token (JWT) every time you initialise the SDK.
To generate an SDK Token you should perform a request to the SDK Token endpoint in the Onfido API:
$ curl https://api.onfido.com/v3/sdk_token \
-H 'Authorization: Token token=YOUR_API_TOKEN' \
-F 'applicant_id=YOUR_APPLICANT_ID' \
-F 'application_id=YOUR_APPLICATION_BUNDLE_IDENTIFIER'
Make a note of the token value in the response, as you will need it later on when initialising the SDK.
Warning: SDK tokens expire 90 minutes after creation.
The application_id is the "Application ID" or "Bundle ID" that was already set up during development.
com.your-company.app-name.
ios/YourProjectName, click on the project root, click the General tab, under Targets click your project name, and check the Bundle Identifier field.build.config. For example, in android/app/build.gradle, it is the value of applicationId.If you are starting from scratch, you can follow the React Native CLI Quickstart https://reactnative.dev/docs/getting-started. For examples, 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 https://docs.expo.io/versions/latest/workflow/customizing/.
Navigate to the root directory of your React Native project. The rest of this section (section 4) will assume you are in the root directory. Run the following command:
$ npm install @onfido/react-native-sdk --save
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
If you want to manually update your build files, you can follow the steps the script takes:
Add the maven link android/build.gradle:
allprojects {
repositories {
mavenCentral()
}
}
Enable multidex in android/app/build.gradle:
android {
defaultConfig {
multiDexEnabled true
}
}
With version 10.0.0 of the Onfido React Native SDK, NFC is enabled by default and offered to customer 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.
NFC dependencies are not included in the SDK to avoid increasing the SDK size when the NFC feature is disabled. To use the NFC feature, you need to include the following dependencies (with the specified versions) in your build script:
implementation "net.sf.scuba:scuba-sc-android:0.0.23"
implementation "org.jmrtd:jmrtd:0.7.34"
implementation "com.madgag.spongycastle:prov:1.58.0.0"
You also need to add the following Proguard rules to your proguard-rules.pro file:
-keep class org.jmrtd.** { *; }
-keep class net.sf.scuba.** {*;}
-keep class org.bouncycastle.** {*;}
-keep class org.spongycastle.** {*;}
-keep class org.ejbca.** {*;}
-dontwarn kotlin.time.jdk8.DurationConversionsJDK8Kt
-dontwarn org.ejbca.**
-dontwarn org.bouncycastle.**
-dontwarn org.spongycastle.**
-dontwarn module-info
-dontwarn org.jmrtd.**
-dontwarn net.sf.scuba.**
Note: You can skip this step if you don't have any custom application class.
⚠️ After the release of version 9.0.0, Onfido RN SDK runs in a separate process. This means that when the Onfido SDK started, a new application instance will be created. To prevent reinitializing 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
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")
}
}
}
Change ios/Podfile to use version 11:
platform :ios, '11.0'
Add descriptions for camera and microphone permissions to ios/YourProjectName/Info.plist:
<plist version="1.0">
<dict>
<!-- Add these four elements: -->
<key>NSCameraUsageDescription</key>
<string>Required for document and facial capture</string>
<key>NSMicrophoneUsageDescription</key>
<string>Required for video capture</string>
<!-- ... -->
</dict>
</plist>
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 ..
With version 10.0.0 of the Onfido React Native SDK, NFC is enabled by default and offered to customer 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.
This 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:
<key>NFCReaderUsageDescription</key>
<string>Required to read ePassports</string>
You have to include the entries below in your app target's Info.plist file to be able to read NFC tags properly.
<key>com.apple.developer.nfc.readersession.felica.systemcodes</key>
<array>
<string>12FC</string>
</array>
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
<string>A0000002471001</string>
<string>A0000002472001</string>
<string>00000000000000</string>
<string>D2760000850101</string>
</array>
You can launch the app with a call to Onfido.start. For example, once you have the sdkTokenFromOnfidoServer, your react component might look like this:
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: 'sdkTokenFromOnfidoServer',
flowSteps: {
welcome: true,
captureFace: {
type: OnfidoCaptureType.VIDEO,
},
captureDocument: {
docType: OnfidoDocumentType.DRIVING_LICENCE,
countryCode: OnfidoCountryCode.GBR,
},
},
})
.then(res => console.warn('OnfidoSDK: Success:', JSON.stringify(res)))
.catch(err => console.warn('OnfidoSDK: Error:', err.code, err.message));
}
render() {
return (
<View style={{marginTop: 100}}>
<Button title="Start Onfido SDK" onPress={() => this.startSDK()} />
</View>
);
}
}
Once you have an added the SDK as a dependency and you have a SDK token, you can configure the SDK:
Example configuration:
config = {
sdkToken: “EXAMPLE-TOKEN-123”,
flowSteps: {
welcome: true,
captureDocument: {
docType: OnfidoDocumentType.DRIVING_LICENSE,
countryCode: OnfidoCountryCode.USA
},
captureFace: {
type: OnfidoCaptureType.VIDEO
}
}
}
sdkToken: Required. This is the JWT sdk token obtained by making a call to the SDK token API. See section Configuring SDK with Tokens.
flowSteps: Required. This object is used to toggle individual screens on and off and set configurations inside the screens.
welcome: Optional. This toggles the welcome screen on or off. If omitted, this screen does not appear in the flow.
true, falseproofOfAddress: Optional. This toggles the proof of address screen on or off. If omitted, this screen does not appear in the flow.
true, falsecaptureDocument: Optional. This object contains configuration for the capture document screen. If docType and countryCode are not specified, a screen will appear allowing the user to choose these values. If omitted, this screen does not appear in the flow.
docType: Required if countryCode is specified.
OnfidoDocumentType: PASSPORT, DRIVING_LICENCE, NATIONAL_IDENTITY_CARD, RESIDENCE_PERMIT, RESIDENCE_PERMIT, VISA, WORK_PERMIT, GENERIC.
Note: GENERIC document type doesn't offer an optimised capture experience for a desired document type.countryCode: Required if docType is specified.
OnfidoCountryCode: Any ISO 3166-1 alpha-3 code. For example: OnfidoCountryCode.USA.captureFace: Optional. This object object containing options for capture face screen. If omitted, this screen does not appear in the flow.
type: Required if captureFace is specified.
OnfidoCaptureType: PHOTO, VIDEO, MOTION.showIntro: Optional. This toggles the intro screen in Selfie step or the intro video on the Video step. Default true
showConfirmation: Optional. This toggles the confirmation screen in Video step (Android only). Default true
manualVideoCapture: Optional. This enables manual video capture (iOS only). Default false
motionCaptureFallback: Required if captureFace is specified as MOTION.
Valid values in OnfidoFaceCapture: OnfidoFaceSelfieCapture, OnfidoFaceVideoCapture.
OnfidoFaceSelfieCapture: type: OnfidoCaptureType.PHOTOOnfidoFaceVideoCapture: type: OnfidoCaptureType.VIDEOIn the scenario that the Motion variant is not supported on the user's device, if you configure the motionCaptureFallback appropriately it will allow the user to capture a Selfie or a Video as a fallback.
Note: Fallback is not used in Android anymore as Motion is supported in all devices and OS versions specified by the SDK.
recordAudio: Required if captureFace is specified as MOTION.
true, falselocalisation: Optional. This object contains localisation configuration. See section Localization for the details.
config = {
sdkToken: “EXAMPLE-TOKEN-123”,
localisation: {
ios_strings_file_name: 'Localizable',
},
flowSteps: {
...
},
}
theme: The theme in which Onfido SDK is displayed. By default, the user's active device theme will be
automatically applied to the Onfido SDK. However, you can opt out from dynamic theme switching at run time
and instead set a theme statically at the build time as shown below. In this case, the flow will always be in displayed
in the selected theme regardless of the user's device theme.
OnfidoTheme: AUTOMATIC, LIGHT, DARK.The response will include a face section if captureFace was specified, document section if captureDocument was specified, or both sections if thery were both requested in the config.
Example:
{
document: {
front: { id: "123-abc" },
back: { id: "345-def" }
},
face: {
id: "456-567",
variant: "VIDEO" // PHOTO or VIDEO
},
}
The SDK will reject the promise any time the Onfido SDK exits without a success. This includes cases where:
Example
{
code: "config_error",
message: "sdkToken is missing"
}
The SDK supports and maintains the following 44 languages:
However, you can add your own translations.
By default, custom localisation is enabled on Android. There is no configuration needed on React Native SDK to enable it. You could also provide custom translation for a locale that we don’t currently support, by having an additional XML strings file inside your resources folder for the desired locale. See Localisation section of Android SDK repo for the details.
You can also provide a custom translation for a locale that Onfido doesn't currently support. There is a simple configuration needed on the React Native SDK to enable custom localisation.
localisation: {
ios_strings_file_name: '<Your .strings file name in iOS app bundle>',
},
cd ios, and open your XCode workspace.Onfido provides the possibility to integrate with our Smart Capture SDK, without the requirement of using this data only through the Onfido API. Media callbacks enable you to control the end user data collected by the SDK after the end user has submitted their captured media. As a result, you can leverage Onfido’s advanced on-device technology, including image quality validations, while still being able to handle end users’ data directly. This unlocks additional use cases, including compliance requirements and multi-vendor configurations, that require this additional flexibility.
This feature must be enabled for your account. Please contact your Onfido Solution Engineer or Customer Success Manager.
To use this feature, use Onfido.addCustomMediaCallback and provide the callback.
Onfido.addCustomMediaCallback(
mediaResult => {
if (mediaResult.captureType === 'DOCUMENT') {
// Callback code here
} else if (mediaResult.captureType === 'FACE') {
// Callback code here
} else if (mediaResult.captureType === 'VIDEO') {
// Callback code here
}
}
);
The callbacks return an object including the information that the SDK normally sends directly to Onfido. The callbacks are invoked when the end user confirms submission of their image through the SDK’s user interface.
Note: Currently, end user data will still automatically be sent to the Onfido backend, but you are not required to use Onfido to process this data.
The callback returns 3 possible objects. Please note that captureType refers to the type of the media capture in each case.
These can be DOCUMENT, FACE or VIDEO.
captureType is DOCUMENT), the callback returns:{
captureType: String
side: String
type: String
issuingCountry: String?
fileData: String
fileName: String
fileType: String
}
Notes:
issuingCountry is optional based on end-user selection, and can be null.fileData is a String representation of the byte array data corresponding to the captured photo of the document.fileData but no additional data.captureType is FACE), the callback returns:{
captureType: String
fileData: String
fileName: String
fileType: String
}
Note: fileData is a String representation of the byte array data corresponding to the captured live photo.
captureType is VIDEO), the callback returns:{
captureType: String
fileData: String
fileName: String
fileType: String
}
Note: fileData is a String representation of the byte array data corresponding to the captured video.
Please note that, for your convenience, Onfido provides the byteArrayStringToBase64 helper function to convert the fileData from String to a Base64 format. Here is an example of how to use it:
let byteArrayString = mediaResult.fileData;
let base64FileData = Onfido.byteArrayStringToBase64(byteArrayString);
While the SDK is responsible for capturing and uploading document photos, live selfies, live videos and motion captures, identity verification reports themselves are generated based on workflows created using Onfido Studio.
For a step-by-step walkthrough of creating an identity verification using Onfido Studio and our SDKs, please refer to our Quick Start Guide.
Alternatively, you can create checks and retrieve report results manually using the Onfido API. You can also configure webhooks to be notified asynchronously of report results.
Note: If you're using API v2 for API calls, please check out API v2 to v3 migration guide to understand which changes need to be applied before starting to use API v3.
Note: If you are testing with a sandbox token, please be aware that report results are pre-determined. You can learn more about sandbox responses here.
Onfido SDK supports the dark theme. By default, the user's active device theme will be
automatically applied to the Onfido SDK. However, you can opt out from dynamic theme switching at run time
and instead set a theme statically at the build time. In this case, the flow will always be in displayed
in the selected theme regardless of the user's device theme. To set a static theme, use the theme parameter in the SDK
initialization config. The value type should be OnfidoTheme.
Valid values in OnfidoTheme are: AUTOMATIC (default value), LIGHT, DARK.
You can customize the SDK's appearance by overriding Onfido's light and dark themes (OnfidoActivityTheme and OnfidoDarkTheme)
in app/src/main/res/values/styles.xml or app/src/main/res/values/themes.xml in the android directory of your project.
Make sure to set OnfidoBaseActivityTheme as the parent of OnfidoActivityTheme and OnfidoBaseDarkTheme as the parent of OnfidoDarkTheme in your style definition.
You can use the following snippet as an example:
<!-- Light theme -->
<style name="OnfidoActivityTheme" parent="OnfidoBaseActivityTheme">
<item name="onfidoColorToolbarBackground">@color/brand_dark_blue</item>
<item name="onfidoColorActionMain">@color/brand_accent_color</item>
</style>
<!-- Dark theme -->
<style name="OnfidoDarkTheme" parent="OnfidoBaseDarkTheme">
<item name="onfidoColorToolbarBackground">@color/brand_dark_blue</item>
<item name="onfidoColorActionMain">@color/brand_accent_color</item>
</style>
The following attributes are currently supported:
onfidoColorToolbarBackground: Background color of the Toolbar which guides the user through the flow
colorPrimaryDark: Color of the status bar (with system icons) above the Toolbar
onfidoColorContentToolbarTitle: Color of the Toolbar's title text
onfidoColorContentMain: Color of primary texts on screen, e.g. titles and regular body texts
onfidoColorContentSecondary: Color of secondary texts on screen, e.g. subtitles
onfidoColorContentNegative: Color of error texts
onfidoColorActionMain: Background color of primary buttons
onfidoColorActionMainPressed: Background color of primary buttons when pressed
onfidoColorActionMainDisabled: Background color of primary buttons when disabled
onfidoColorContentOnAction: Text color of primary buttons
onfidoColorContentOnActionDisabled: Text color of primary buttons when disabled
onfidoColorActionSecondary: Background color of secondary buttons
onfidoColorActionSecondaryPressed: Background color of secondary buttons when pressed
onfidoColorActionSecondaryDisabled: Background color of secondary buttons when disabled
onfidoColorContentOnActionSecondary: Text color of secondary buttons
onfidoColorContentOnActionSecondaryDisabled: Text color of secondary buttons when disabled
onfidoColorActionSecondaryBorder: Border of the secondary buttons
onfidoColorActionSecondaryBorderDisabled: Border of the secondary buttons when disabled
onfidoColorProgressTrack: Track color of progress indicators (background color)
onfidoColorProgressIndicator: Indicator color of progress indicators (foreground color)
colorAccent: Defines alert dialogs' accent color, and text input fields' focused underline, cursor, and floating
label color
onfidoColorWatermark: Color of the Onfido logo and co-brand logo in the footer of screens
onfidoColorDisclaimerBackground: Background color of disclaimer boxes
onfidoColorContentDisclaimer: Text color of disclaimer boxes
onfidoColorIconDisclaimer: Icon color of disclaimer boxes
onfidoColorIconStroke: Stroke color of icons
onfidoColorIconFill: Fill color of icons
onfidoColorIconBackground: Background color of icons
onfidoColorIconAccent: Background color of accented icons
Note:
The usage of color.json and the updateColors command is now deprecated for Android. Please provide the theme attributes in your styles.xml or themes.xml as mentioned above.
To customize supported dimnesions, you can add an Android resource file named dimens.xml in the following directory of your project: android/app/src/main/res/values.
Please see the snippet below as an example.
<resources>
<dimen name="onfidoButtonCornerRadius">8dp</dimen>
</resources>
The following dimensions are currently supported:
onfidoButtonCornerRadius: The corner radius of all buttons in the SDK, provided in the dp unitYou can customize the SDK by adding a colors.json file to your xcode project as bundle resource. The file should contain a single json object with the desired keys and values. For example:
{
"onfidoPrimaryColor": "#FF0000",
"backgroundColor": {
"light": "#FCFCFD",
"dark": "#000000"
},
"onfidoPrimaryButtonTextColor": "#FFFFFF",
"onfidoPrimaryButtonColorPressed": "#FFA500",
"interfaceStyle": <"unspecified" | "light" | "dark">,
"secondaryTitleColor": "#FF0000",
"secondaryBackgroundPressedColor": "#FF0000",
"buttonCornerRadius": 20,
"fontFamilyTitle": "FONT_NAME_FOR_TITLES",
"fontFamilyBody": "FONT_NAME_FOR_CONTENT",
}
The following attributes are currently supported:
onfidoPrimaryColor: Background color of views such as capture confirmation buttons, back navigation button, and play and pause buttons in liveness/video capture introbackgroundColor: Background color used for all non-capture views. Can be defined for both light and dark modeonfidoPrimaryButtonTextColor: Text color of labels included in views such as capture confirmation buttonsonfidoPrimaryButtonColorPressed: Defines the background color of capture confirmation buttons when pressedinterfaceStyle: Defines the supported interface styles ("unspecified" by default, which follows the sytem's interface style)secondaryTitleColor: Secondary button text and border colorsecondaryBackgroundPressedColor: Secondary button pressed state colorbuttonCornerRadius: Border corner radius for all buttons (default value is 5.0)fontFamilyTitle: Name of the font used for title textsfontFamilyBody: Name of the font used for body/content textsYou can check out the iOS SampleApp for example usage. When running on an iOS device, the values will be picked up dynamically at runtime.
Dark Mode Customization
interfaceStyle allows you to force light or dark mode via dark and light respectively, or follow the system's interface style with unspecified.
Note:
The usage of onfidoIosSupportDarkMode in the color.json is now deprecated. Please use interfaceStyle instead.
Once you are happy with your integration and are ready to go live, please contact client-support@onfido.com to obtain live versions of the API token and the mobile SDK token. You will have to replace the sandbox tokens in your code with the live tokens.
A few things to check before you go live:
Resolving dependency conflicts
Here are some helpful resources if you are experiencing dependency conflicts between this React Native SDK and other packages your app uses:
General advice
If you see issues, you can try removing node_modules, build directories, and cache files. A good tool to help with this is react-native-clean-project
Below is a list of known differences in expected behavior between the Onfido Android and iOS SDKs this React Native SDK wraps:
passport uploaded through the iOS SDK will have the side attribute set to null, while those uploaded via Android will have side as front.Should you encounter any technical issues during integration, please contact Onfido's Customer Support team via email, including the word ISSUE: at the start of the subject line.
Alternatively, you can search the support documentation available via the customer experience portal, public.support.onfido.com.
Previous versions of the SDK will be supported for a month after a new major version release. Note that when the support period has expired for an SDK version, no bug fixes will be provided, but the SDK will keep functioning (until further notice).
Copyright 2023 Onfido, Ltd. All rights reserved.
The Onfido React Native SDK is available under the MIT license.
[11.0.0] - 2024-03-06
FAQs
Onfido React Native SDK
The npm package @onfido/react-native-sdk receives a total of 12,018 weekly downloads. As such, @onfido/react-native-sdk popularity was classified as popular.
We found that @onfido/react-native-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.