DocumentationAPI Reference
Help CenterAPI ChangelogOpenAPI SpecStatus
Documentation

Android SDK v1 Integration Guide

Android Inquiry SDK Integration Guide and Technical Documentation

❗️

Looking for v2?

If your Template starts with tmpl_, you're on v1.

We will stop making updates to v1 on December 31, 2022. You will still be able to create inquiries, but no new features or fixes will be available. We recommend moving to v2 for access to the latest product improvements- please see migration to v2 section or contact [email protected].

📘

Technical Documentation

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

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 latest

Usage

Launching the Inquiry flow

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

Kotlin

// pick any number and then use it later to retrieve the response
val VERIFY_REQUEST_CODE = 43
// Get the template ID from the Dashboard
// https://withpersona.com/dashboard/integration
val TEMPLATE_ID = "tmpl_JAZjHuAT738Q63BdgCuEJQre"
// ...

Inquiry.fromTemplate(TEMPLATE_ID)
  .environment(Environment.SANDBOX)
  .build()
  .start(this, VERIFY_REQUEST_CODE)

Java

// pick any number and then use it later to retrieve the response
static final int  VERIFY_REQUEST_CODE = 43;
// Get the template ID from the Dashboard
// https://withpersona.com/dashboard/integration
static final String TEMPLATE_ID = "tmpl_JAZjHuAT738Q63BdgCuEJQre";
// ...

Inquiry.fromTemplate(TEMPLATE_ID)
        .environment(Environment.SANDBOX)
        .build()
        .start(this, VERIFY_REQUEST_CODE);

Receiving the response

Kotlin

// overwriting the Activity#onActivityResult
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
  super.onActivityResult(requestCode, resultCode, data)
  if (requestCode == VERIFY_REQUEST_CODE) {
    when(val result = Inquiry.onActivityResult(data)) {
      is Inquiry.Response.Success -> {
        // ...
      }
      is Inquiry.Response.Failure -> {
        // ...
      }
      Inquiry.Response.Cancel -> {
        // ...
      }
      is Inquiry.Response.Error -> {
        // ...
      }
    }
  }
}

Java

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
  super.onActivityResult(requestCode, resultCode, data);
  if (requestCode == VERIFY_REQUEST_CODE) {
    Inquiry.Response response = Inquiry.onActivityResult(data);
    if (response instanceof Inquiry.Response.Success) {
      Inquiry.Response.Success success = (Inquiry.Response.Success) response;
      // ...
    } else if (response instanceof Inquiry.Response.Failure) {
      Inquiry.Response.Failure failure = (Inquiry.Response.Failure) response;
      // ...
    } else if (response instanceof Inquiry.Response.Cancel) {
      // ...
    } else if (response instanceof Inquiry.Response.Error) {
      Inquiry.Response.Error error = (Inquiry.Response.Error) response;
      // ...
    }
  }
}

Customization

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

Theming

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="colorAccent">#6ec6ff</item>
    <item name="colorPrimaryDark">#0069c0</item>
  </style>
</resources>

Then set in as the theme in Inquiry builder.

Inquiry.fromTemplate(TEMPLATE_ID)
  .theme(R.style.BlueDemoTheme)
  .build()
  .start(this, VERIFY_REQUEST_CODE)

Customizable attributes include colors, fonts, text alignments, images, and animations.

Customizing Fonts

In order to specify fonts on Android, the fonts either must be system fonts or fonts bundled into your application.

Providing a custom font

If you would like to provide your own custom font, first create a font resource by following the follow guide: https://developer.android.com/guide/topics/ui/look-and-feel/fonts-in-xml.

Then you can supply your custom font in styles.xml:

<resources>
  <!-- other style declarations -->
  <style name="CustomFontDemoTheme" parent="@style/Persona.Inquiry.Theme">
    <item name="fontFamily">@font/custom_font</item>
  </style>
</resources>

Replacing Strings

Replace any title, body, or button text by overwriting our strings in your strings.xml file.

<resources>
  <!-- some of your strings.xml strings -->
  <string name="persona_inquiry_start_title">This is the start screen title.</string>
  <string name="persona_inquiry_start_body">This is below that in the body.</string>
  <string name="persona_inquiry_start_button">I\'m a button!</string>
  <!-- more of your strings.xml strings -->
</resources>

Available String Keys

  • persona_contact_support_body
  • persona_contact_support_button
  • persona_contact_support_title
  • persona_countryselect_body
  • persona_countryselect_button
  • persona_countryselect_title
  • persona_governmentid_failed_title
  • persona_governmentid_start_body
  • persona_governmentid_start_title
  • persona_governmentid_submitting_body
  • persona_governmentid_submitting_title
  • persona_inquiry_complete_body
  • persona_inquiry_complete_button
  • persona_inquiry_complete_title
  • persona_inquiry_failed_body
  • persona_inquiry_failed_button
  • persona_inquiry_failed_title
  • persona_inquiry_start_body
  • persona_inquiry_start_button
  • persona_inquiry_start_title
  • persona_selfie_failed_body
  • persona_selfie_failed_button
  • persona_selfie_failed_title
  • persona_selfie_start_body
  • persona_selfie_start_button
  • persona_selfie_start_title
  • persona_selfie_submitting_body
  • persona_selfie_submitting_title
  • persona_database_start_body
  • persona_database_start_button
  • persona_database_start_title