Integrating Sentinel in Android applications

This guide covers how to add the Persona Sentinel SDK to your Android project and how to use the SDK.

Requirements

Your application needs a minSdkVersion set to API 23 (Android 6.0, Marshmallow) or higher.

Adding Persona to your project

In your app/build.gradle file (or wherever you plan on using the SDK), include the following:

Kotlin

repositories {
  // ...
  maven {
    url = uri("https://sdk.withpersona.com/android/releases")
  }
}

android {
  // ...
  compileOptions {
    sourceCompatibility = JavaVersion.VERSION_17
    targetCompatibility = JavaVersion.VERSION_17
  }
}

dependencies {
  // ...
  implementation("com.withpersona.sdk2:sentinel:X.Y.Z")
  // ...
}

Groovy

repositories {
  // ...
  maven {
    url 'https://sdk.withpersona.com/android/releases'
  }
}

android {
  // ...
  compileOptions {
    sourceCompatibility JavaVersion.VERSION_17
    targetCompatibility JavaVersion.VERSION_17
  }
}

dependencies {
  // ...
  implementation 'com.withpersona.sdk2:sentinel:X.Y.Z'
  // ...
}

Required permissions

Our manifest files declare the following permission:

<uses-permission android:name="android.permission.INTERNET" />

Versioning

If you’re also using the Inquiries Android SDK, make sure both implementations use the same SDK version.

Usage

The Persona Sentinel SDK collects passive signals from customers via events. The following sections describe how to configure and trigger a Sentinel event.

Triggering a Sentinel event

The Sentinel object is used to build and trigger an event.

Sentinel
    .newEventBuilder(
        clientToken = CLIENT_TOKEN,
        transactionTypeId = TRANSACTION_TYPE_ID,
    )
    .contextString()  // an optional string
    .identifiers()    // an optional array of strings
    .environmentId()  // an optional Persona environment ID: defaults to your production environment.
    .accountReferenceId("...") // optionally include account reference id for this event
    .autoCreateAccount(true)  // an optional boolean: defaults to true. Controls whether an account is automatically created.
    .autoCreateAccountTypeId("acttp_...")  // an optional account type token: defaults to the transaction type's configured default account type.
    .build()
    .trigger(context)

You can trigger events using one of two methods:

• [Preferred] trigger(Context) triggers the event immediately, but it is a suspending function. It returns a kotlin.Result object you can use to determine whether the event was logged successfully.
• triggerAsync(context) also requires a Context and logs the event asynchronously without blocking the calling thread.