🚧

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]

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_1_8
    targetCompatibility JavaVersion.VERSION_1_8
  }
}

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:

Usage

📘

Technical Documentation

If you want to dive right in to the Javadocs, you can do so here.

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_Ygs16MKTkA6obnF8C3Rb17dm"
// ...

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_Ygs16MKTkA6obnF8C3Rb17dm";
// ...

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", "Susan")
      .field("name_last", "Realman")
      .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_123456")
  .build()

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

val inquiry = Inquiry.fromInquiry("inq_123456")
  .sessionToken("ABD1234567890")
  .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 Persona Inquiry Sdk will log the error to the Inquiry Session and then 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.

The error class is described below:

  /**
   * Object returned when there is a problem during the Inquiry flow
   *
   * @property debugMessage reason why the Inquiry did not complete correctly
   */
  class Error(val debugMessage: String) : InquiryResponse()

The possible values for debugMessage include:

object InquiryErrorMessages {
  const val networkError = "There was a problem reaching the server."
  const val cameraPermissionError = "There was an issue with camera permissions."
  const val configurationError = "The SDK needs a template ID that starts with `itmpl_`. If your template ID starts with `tmpl_`, you should use version v1.x of the Persona Android SDK. https://docs.withpersona.com/docs/mobile-sdks-v1"
  const val unexpectedError = "There was an unexpected error."
}

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()

🚧

If you are currently using theme(@StyleRes theme: Int) to initalize your theme, please see our guide for migrating from client side theming to server side theming via the Persona dashboard.

There are some properties that are not supported yet, and others that cannot be applied without component-level theming (e.g. custom assets and visuals). If you run into gaps that block your migration, please reach out.

Custom Fonts

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.