Android Integration Guide
Android Inquiry SDK Integration Guide and Technical Documentation
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:
Data Types | Collected | Shared | Processed Ephemerally | Required or Optional | Purposes |
---|---|---|---|---|---|
Device or other IDs | Yes | No | No | Required | Fraud Prevention |
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'
}
Updated 28 days ago