DocumentationAPI Reference
DocumentationAPI Reference

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.

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.sdk:inquiry:X.Y.Z'
  // ...
}

Inquiry SDK latestInquiry SDK latest

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

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