React Native Integration Guide
React Native Inquiry SDK v2 Integration Guide and Technical Documentation
v1 or v2?
If your Template ID starts with
itmpl_
, you're in the right place. Otherwise, you will want to look at the v1 section. If you are interested in moving to v2, please contact [email protected]
Installation
To install the Persona React Native SDK within your React Native application, if you use yarn
to manage your project dependencies
yarn add react-native-persona
If you use npm
to manage your project dependencies
npm i react-native-persona
Configure Android
Add Android Maven repository
Open your android/build.gradle
file. Add the Persona Maven repository to the bottom of your repository list.
allprojects {
repositories {
// ...
maven {
url 'https://sdk.withpersona.com/android/releases'
}
}
}
Make sure minimum compile is over 30
In the app/build.gradle
file, make sure the compileSdkVersion
is at least 31.
android {
// ...
compileSdkVersion = 31
// ...
}
If you change the targetSdkVersion
to be above 30 as well, you'll need to set android:exported="true"
on your Activity in the AndroidManifest.xml
file.
Common Android issues
If you're using expo and can't find your android/build.gradle
file try running npx expo run:android
to generate the native android project for your app. If your app doesn't load our Android native module you'll receive the following runtime error:
Cannot read property 'startInquiry' of null
Configure iOS
Install iOS pods
Ensure Cocoapods v1.10.x or higher is installed.
cd ios; pod install
iOS Permissions
Modify your Info.plist
file to add the appropriate Privacy Usage Descriptions (if not already present). Navigate to your project's settings in Xcode and click the Info tab.
Info.plist Key | Note |
---|---|
Privacy - Camera Usage Description NSCameraUsageDescription | Used to access Camera for Government Id, Selfie, and Document flows. |
Privacy - Photo Library Usage Description NSPhotoLibraryUsageDescription | Optional. Used on Document flows and on Government Id flows when file upload is enabled. |
Privacy - NFC Scan Usage Description NFCReaderUsageDescription | Optional. Used for Passport NFC flows. |
iOS minimum deployment target
Our native iOS SDK requires a minimum iOS deployment target of 13.0.
In your project's ios/Podfile
, ensure your platform
target is set to 13.0.
platform :ios '13.0'
iOS Privacy Configuration
This SDK collects a user’s IDFV for fraud prevention purposes. In App Store Connect > Your App > App Privacy, if you haven’t already add in a “Device Identifier,” and fill out the questionnaire with the following answers:
- Usage: App Functionality (covers fraud prevention)
- Are the device IDs collected from this app linked to the user’s identity? Yes
- Do you or your third-party partners use device IDs for tracking purposes? No
Common iOS issues
If you're using expo and can't find your ios
folder, try running npx expo run:ios
to generate the native iOS project for your app. Then run pod install
from the ios
folder. If your app doesn't load our iOS native module you'll receive the following runtime error:
Your JavaScript code tried to access a native module that doesn't exist.
Usage
The Persona Inquiry flow can be initiated with either a template ID
or an inquiry ID
.
Please refer to the code sample below and replace my_template_id
with your template ID
. You can find your template ID
on the Persona Dashboard under Integration.
This starts the Inquiry flow and takes control of the user interface. Once the flow completes, the control of the user interface is returned to the app and the appropriate callbacks are called.
import {Inquiry, Environment} from 'react-native-persona';
// ...
<Button
title="Start Inquiry"
onPress={() => {
Inquiry.fromTemplate('my_template_id')
.environment(Environment.SANDBOX)
.onComplete((inquiryId, status, fields) =>
Alert.alert(
'Complete',
`Inquiry ${inquiryId} completed with status "${status}."`,
),
)
.onCanceled((inquiryId, sessionToken) =>
Alert.alert('Canceled', `Inquiry ${inquiryId} was cancelled`),
)
.onError(error => Alert.alert('Error', error.message))
.build()
.start();
}}
/>
Inquiry Fields
The onComplete
callback returns fields
, which is an object containing information extracted during the inquiry. Refer to the field schema for a given template in the Persona Dashboard.
Configuration options
Some different configuration example can be found below
// Configuration with only a template ID
Inquiry.fromTemplate("my_template_id").build().start();
// Configuration with only a template ID in the sandbox
Inquiry.fromTemplate("my_template_id")
.environment(Environment.SANDBOX)
.build()
.start();
// Configuration with a template and reference ID
Inquiry.fromTemplate("my_template_id")
.referenceId("myReference")
.build()
.start();
// Configuration passing fields to profile data into the inquiry.
// Refer to the field schema for a given template in the Persona Dashboard.
Inquiry.fromTemplate("my_template_id")
.fields(
Fields.builder()
.string('nameFirst', 'Alexander')
.string('nameLast', 'example')
.build(),
)
.build()
.start();
// Configuration with only an inquiry ID
Inquiry.fromInquiry("my_inquiry_id").build().start();
// Configuration resuming an inquiry session with an access token
Inquiry.fromInquiry("my_inquiry_id")
.sessionToken("SOME_SESSION_TOKEN")
.build()
.start();
Custom Copy and Localization
Work with your account team to edit copy and localization for a given Inquiry Template. Self serve support for editing copy and localizations is coming to the Persona Dashboard soon.
Theming
Set your own colors, buttons, fonts and more.
You can configure the styles that are applied to the inquiry template in the Persona Dashboard. For more information on using the theme editor, see our help article.
Ensure your app is using react-native-persona v2.4.0 or higher to enable Server Side Theming.
Custom Fonts
The React Native SDK will use the font name set in the Persona Dashboard for various text fields. Note that the font must be bundled in the hosting application in order to be loaded at runtime. The SDK will automatically lowercase the font name specified in the Persona Dashboard when rendering on Android and will replace any -
or space characters with _
to allow compatibility with Android resource naming conventions.
To bundle your own custom font on Android, create a font resource by following the follow guide: https://developer.android.com/guide/topics/ui/look-and-feel/fonts-in-xml.
To bundle your own custom font on iOS, add a font file to the Xcode project by following the guide here: https://developer.apple.com/documentation/uikit/text_display_and_fonts/adding_a_custom_font_to_your_app.
Dark mode
Work with your account team to enable a dark mode variant of your theme. Self serve support for dark mode is coming to the Persona Dashboard soon.
Legacy Client Side Theming
Client side theming for our mobile SDKs is now deprecated. For information on legacy client side theming, view React Native SDK v2 Legacy Client Side Theming.
Updated about 1 month ago