The Persona Inquiry flow lets you securely and seamlessly collect your user's information.

Integration

Integrate the Persona Inquiry flow directly into your Android app with our native SDK.

Requirements - Make sure the SDK is compatible

Your application needs to have a minSdkVersion set to API 21 (Lollipop, 5.0) or higher.

Dependencies - Adding Persona to your project

In your app/build.gradle file (or wherever you plan on using the SDK) include the following:

repositories {
  google()
  jcenter()
  maven {
    url 'https://sdk.withpersona.com/android/releases'
  }
}

android {
  // ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }
}

dependencies {
  // ...
  implementation 'com.withpersona.sdk2:inquiry:X.Y.Z'
  // ...
}

Privacy Configuration

This SDK collects a user’s App-Set ID for Fraud Prevention purposes. When publishing to the Play Store, disclose the usage of Device Identifiers as follows:

Required permissions

Our manifest files declare the following permissions.

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />

If using our optional NFC package, <uses-permission android:name="android.permission.NFC" /> is also included.

Usage

Register for Inquiry's Result

Use the androidx.activity.ComponentActivity#registerForActivityResult or androidx.fragment.app.Fragment#registerForActivityResult method for retrieving the Inquiry result. Set it up using the Inquiry.Contract() as a val.

The SDK still supports launching an Intent and parsing the result with Inquiry#onActivityResult, but that method is deprecated.

Kotlin

val getInquiryResult =
  registerForActivityResult(Inquiry.Contract()) { result ->
    when (result) {
      is InquiryResponse.Complete -> {
        // ... completed flow
      }
      is InquiryResponse.Cancel -> {
        // ... abandoned flow
      }
      is InquiryResponse.Error -> {
        // ... something went wrong
      }
    }
  }

Java

ActivityResultLauncher<Inquiry> getInquiryResult =
    registerForActivityResult(new Inquiry.Contract(),
        new ActivityResultCallback<InquiryResponse>() {
          @Override public void onActivityResult(InquiryResponse result) {
            if (result instanceof InquiryResponse.Complete) {
              InquiryResponse.Complete complete = (InquiryResponse.Complete) result;
              // ... completed flow
            } else if (result instanceof InquiryResponse.Cancel) {
              InquiryResponse.Cancel cancel = (InquiryResponse.Cancel) result;
              // ... abandoned flow
            } else if (result instanceof InquiryResponse.Error) {
              InquiryResponse.Error error = (InquiryResponse.Error) result;
              // ... something went wrong
            }
          }
        });

Build and Launch the Inquiry

The Inquiry flow is initiated with a builder pattern based on either Inquiry Template ID, Inquiry Template Version, or Inquiry ID. Everything on the builder is optional: theme, referenceId, accountId, and environment (which defaults to PRODUCTION).

Kotlin

// Get the template ID from the Dashboard
// <https://withpersona.com/dashboard/integration>
val TEMPLATE_ID = "itmpl_EXAMPLE"
// ...

val inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
  .environment(Environment.SANDBOX)
  .build()
// ...

getInquiryResult.launch(inquiry)

Java

// Get the template ID from the Dashboard
// <https://withpersona.com/dashboard/integration>
static final String TEMPLATE_ID = "itmpl_EXAMPLE";
// ...

Inquiry inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
    .environment(Environment.SANDBOX)
    .build();
// ...

getInquiryResult.launch(inquiry);

Linking an Inquiry to your Users

To make it easier to find Inquiries in the Persona Dashboard, we recommend passing in your system's user ID for the Inquiry reference ID.

val inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
  .referenceId("myUser_123")
  .build()

Pre-writing to the Inquiry

If you want to add extra information to the Inquiry before the user even starts, you can pass them in as Fields.

val inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
  .fields(
    Fields.Builder()
      .field("name_first", "Alexander")
      .field("name_last", "Example")
      .build()
  )
  .build()

Starting/Resuming an Inquiry from ID

When you create an Inquiry on the server, you can pass the Inquiry ID instead of the Template ID.

val inquiry = Inquiry.fromInquiry("inq_EXAMPLE")
  .build()

If the Inquiry has already started, you will need to also pass in the session token.

val inquiry = Inquiry.fromInquiry("inq_EXAMPLE")
  .sessionToken("ABD1234567890")
  .build()

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:

val inquiry = 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.

val inquiry = Inquiry.fromTemplate("itmpl_EXAMPLE")
  .routingCountry(RoutingCountry.DE.name)
  .build()

Errors

It is rare but, the Persona Inquiry SDK may encounter a few categories of client side errors that can not be resolved. When unrecoverable errors are encountered, the sdk will immediately callback to the main application with a debug description of the error.

The most common reasons the Persona Inquiry SDK will error include unrecoverable networking errors, misconfigured templates (should only be encountered during development), or failing to establish a connection the the device camera.

Customization

Make the Persona Inquiry flow look and feel like your app.

Custom Styling

Set your own colors, buttons, fonts, and more. This can be done via the Persona Dashboard. For more information on using the theme editor, see our help article.

To make other optional customizations such as custom loading icons, make a style in your styles.xml file that extends the Persona style.

The following example would generate R.style.CustomLoadingIconTheme.

<resources>
  <!-- other style declarations -->
  <style name="CustomLoadingIconTheme" parent="@style/Persona.Inquiry.Theme">
    <item name="personaInquiryLoadingLottieRaw">@raw/custom_loading_icon</item>
  </style>
</resources>

Then set it as the theme in Inquiry builder.

val customLoadingIconTheme = ServerThemeSource(R.style.CustomLoadingIconTheme)
val inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
  .theme(customLoadingIconTheme)
  .build()

Custom Fonts

By default, the Android SDK will use the device's system font. Font families specified in the Persona Dashboard only apply to the web flow will not be used by mobile SDKs unless you bundle your own font files.

The Android 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 and will replace any - or space characters with _ to allow compatibility with Android resource naming conventions.

For example, if you choose the font 'Rubik' in your template's Theme configuration, you will need to add a font file named Rubik.ttf (or any compatible format) to your project's res/font directory.

Government Id NFC Integration

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

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