DocumentationAPI Reference
Help CenterAPI ChangelogOpenAPI SpecStatus
Documentation
Help CenterAPI ChangelogOpenAPI SpecStatus

Android SDK v2 Integration Guide

Android 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].

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.

Releases

Watch this repo for new Releases to be notified when new versions of the android SDK are available.

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

Inquiry SDK latest

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:

Data TypesCollectedSharedProcessed EphemerallyRequired or OptionalPurposes
Device or other IDsYesNoNoRequiredFraud Prevention

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. First, make a style in your styles.xml file that extends the Persona style.

The following example would generate R.style.BlueDemoTheme.

<resources>
  <!-- other style declarations -->
  <style name="BlueDemoTheme" parent="@style/Persona.Inquiry.Theme">
    <item name="colorPrimary">#2196f3</item>
    <item name="colorSecondary">#6ec6ff</item>
    <item name="colorPrimaryVariant">#0069c0</item>
  </style>
</resources>

Then set it as the theme in Inquiry builder.

val inquiry = Inquiry.fromTemplate(TEMPLATE_ID)
  .theme(R.style.BlueDemoTheme)
  .build()

Updated about 2 years ago