🚧

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.

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.