🚧

Is your React Native app ready for AGP8?

Version 8.x of Android Gradle Plugin (AGP) requires breaking charges from both library and app developers. Starting in React Native 0.73, AGP8 and Java 17 will be required for Android apps.

We've added support for AGP8 starting in v2.7.0 of our RN SDK. However, due to the breaking changes required, this version will only work if your app is also on AGP8.

Support for AGP7 will continue under the v2.6.x branch of our RN SDK. Please use that release branch until you are ready to make the switch to AGP8, at which point you can upgrade to our latest releases.

Installation

To install the Persona React Native SDK within your React Native application, if you use yarn to manage your project dependencies

# Install the latest AGP8 compatible sdk
yarn add react-native-persona@">=2.7.0"

# Install the latest AGP7 compatible sdk
yarn add react-native-persona@"<2.7.0"

If you use npm to manage your project dependencies

# Install the latest AGP8 compatible sdk
npm i react-native-persona@">=2.7.0"

# Install the latest AGP7 compatible sdk
npm i react-native-persona@"<2.7.0"

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'
        }
    }
}

Ensure minimum compile sdk

In the app/build.gradle file, make sure the compileSdkVersion is at least 33.

android {
   // ...
   compileSdkVersion = 33
   // ...
}

Common Android issues

android/build.gradle not found

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

After running this command and generating the build.gradle file, you can then configure it according to the instructions above.

Standard library functions not supported, e.g. defineEntityReplacementText() not supported

Please ensure you are on at least version 8.0 of Android Gradle Plugin (AGP).

We've added support for AGP8 starting in v2.7.0 of our RN SDK. However, due to the breaking changes required, this version will only work if your app is also on AGP8.

Support for AGP7 will continue under the v2.6.x branch of our RN SDK. Please use that release branch until you are ready to make the switch to AGP8, at which point you can upgrade to our latest releases.

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.

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

ios/ folder not found

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('itmpl_EXAMPLE')
      .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("itmpl_EXAMPLE").build().start();

// Configuration with only a template ID in the sandbox
Inquiry.fromTemplate("itmpl_EXAMPLE")
   .environment(Environment.SANDBOX)
   .build()
   .start();

// Configuration with a template and reference ID
Inquiry.fromTemplate("itmpl_EXAMPLE")
   .referenceId("myUser_123")
   .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("itmpl_EXAMPLE")
  .fields(
    Fields.builder()
      .string('nameFirst', 'Alexander')
      .string('nameLast', 'Example')
      .build(),
  )
  .build()
  .start();

// Configuration with only an inquiry ID
Inquiry.fromInquiry("inq_EXAMPLE").build().start();

// Configuration resuming an inquiry session with an access token 
Inquiry.fromInquiry("inq_EXAMPLE")
    .sessionToken("SOME_SESSION_TOKEN")
    .build()
    .start();

Overriding device locale

Our SDK will automatically use the language and region selected on a users device to determine localization. If your app has specific localization requirements independent of user's device settings, you can pass the localization directly to the InquiryBuilder as follows:

Inquiry.fromTemplate("itmpl_EXAMPLE")
  .locale("fr")
  .build()

Geographical Routing

If you need to specify a geography for your network requests, you can use .routingCountry on your InquiryTemplateBuilder. Your data will always be stored in the region associated with your Persona account, but you will notice latency if your requests are routed to the wrong region. Our SDK will automatically pick the correct geography after the initial request but if you know your desired geo, you can request it to eliminate latency on the initial request.

Inquiry.fromTemplate("itmpl_EXAMPLE")
  .routingCountry(RoutingCountry.DE)
  .build()

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.

Government Id NFC Integration

Android

To enable Government Id NFC functionality on Android, add the following plugin to your build.gradle file:

repositories {
  ...
  maven { url = uri("https://jitpack.io") }
  ...
}
  
...

dependencies {
  implementation 'com.withpersona.sdk2:nfc-impl:X.Y.Z'
}

Note that the nfc-impl version must exactly match the version of the main Persona module in order to work properly.

iOS

To enable Government Id NFC functionality on iOS, follow the instructions below:

• Add the Nfc pod subspec and base pod to your Podfile:
  pod 'RNPersonaInquiry2', :path => '../node_modules/react-native-persona'
pod 'RNPersonaInquiry2/Nfc', :path => '../node_modules/react-native-persona'
• Add the NFC capability to your app (target → signing & capabilities → + Capability → Near Field Communication Tag Reading). You will also need to add the NFC capability to the Identifier for the app in the Apple Developer portal.
• Make sure that the entitlements file for your app includes both TAG and PACE for the Near Field Communication Tag Reader Session Formats :
  text

  <key>com.apple.developer.nfc.readersession.formats</key>
  <array>
    <string>TAG</string>
    <string>PACE</string>
  </array>
  

• Add a Privacy - NFC Scan Usage Description to your info.plist file, along with a description.
• Add a ISO7816 application identifiers for NFC Tag Reader Session to your info.plist file with these values in the following order: A0000002471001, A0000002472001, and 00000000000000

Video Integration

Android

To enable video recording over WebRTC on Android, add the following to your build.gradle file:

dependencies {
  implementation 'com.withpersona.sdk2:webrtc-impl:X.Y.Z'
}

Note that the webrtc-impl version must exactly match the version of the main Persona module in order to work properly.

iOS

To enable video recording over WebRTC on iOS, follow the instructions below:

• Add the WebRtc pod subspec and base pod to your Podfile:
  pod 'RNPersonaInquiry2', :path => '../node_modules/react-native-persona'
pod 'RNPersonaInquiry2/WebRtc', :path => '../node_modules/react-native-persona'
• Add a Privacy - Microphone Usage Description to your info.plist file, along with a description.

To enable local video recording upload on iOS follow these steps:

• Add a Privacy - Microphone Usage Description to your Info.plist file.

To enable GPS collections on iOS follow these steps:

• Add a Privacy - Location When In Use Usage Description to your Info.plist file.

Licenses

See here for a list of the 3rd party software that we use and their associated licenses. Be sure to include these licenses in your app.