Guides

Android SDK 3.4.x

Suggest Edits

SDK v3.4.x Requirements

Installation

Reference the following Recipes for examples of successful NeuroID SDK integrations.

📱
Android Layouts using Jitpack Installation
Open Recipe
📱
Android Layouts Installation
Open Recipe

To see available versions, please visit Release Versions.


Add the NeuroID SDK to the Project

JitPack Installations

Add the JitPack repository to your settings.gradle file.

repositories {
 ...
 maven { url 'https://jitpack.io' }  
}

Add the dependency to your build.gradlefile. To see available versions, please visit [Released Versions]. 

dependencies {
 debugImplementation 'com.github.neuro-id.neuroid-android-sdk:android-sdk-debug:vX.X.X' // Dev Environment
 implementation 'com.github.neuro-id.neuroid-android-sdk:android-sdk:vX.X.X' // Prod Environment
}

🚧

Required for mimifyEnabled True Releases.

Add the following ProGuard rule in your ProGuard file:

-keep class com.neuroid.** { *; }
-keep class retrofit2.** { *; }
-keep class com.google.gson.** { *; }

Manual Installations

Installing the NeuroID SDK manually requires the download of both the SDK .aar files and adding additional dependencies into your Gradle file. This is normally handled by the .pom file included in JitPack.

First, download the SDK and copy the .aar file to the libs folder of your project.

  • Debug/QA Environment: neuro-id-android-sdk-androidLib-debug.aar
  • Release/Production Environment: neuro-id-android-sdk-androidLib-release.aar

Add the following dependencies to your application Gradle (app/build.gradle):

// Debug
implementation files('libs/neuro-id-android-sdk-androidLib-debug.aar')

// Release
implementation files('libs/neuro-id-android-sdk-androidLib-release.aar')

Add the following additional libraries to the dependency section in the app/build.gradle file -- these help ensure the SDK will function properly.

implementation 'org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2'
implementation 'androidx.security:security-crypto:1.1.0-alpha03'
implementation 'com.google.code.gson:gson:2.10.1'
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
implementation 'com.squareup.okhttp3:okhttp:4.9.2'

🚧

Required for mimifyEnabled True Releases

Add the following ProGuard rule in your ProGuard file.

-keep class com.neuroid.** { *; }
-keep class retrofit2.** { *; }
-keep class com.google.gson.** { *; }-keep class com.neuroid.** { *; }

Java Projects

If your project uses 100% Java, and only if it uses Java, add the following dependency:

implementation 'androidx.core:core-ktx:1.7.0'

Initialize the SDK

NeuroID will provide two client keys, one for Production and one for Testing. The setup for both environments is the same, only differentiated by the key.

To initialize the SDK call NeuroID.Builder(...params...).build(). The Builder method takes three parameters:

  • application which is the Android Application class.
  • clientKey which should receive either your Production, or Testing key.
  • isAdvancedDevice which is a Boolean parameter used to indicate if you are using the Advanced Device SDK in addition to the standard SDK. Please see the Advanced Device Library section for more information.
// Add this import to each view you will be tracking
import com.neuroid.tracker.NeuroID

...

// This should be called once, from your ApplicationMain's
//  `onCreate` method 
NeuroID.Builder(
            this,
            "your_api_key_goes_here",
        ).build()

🚧

MultiDexApplication Usage

If the application is not of type MultiDexApplication, you will need to create a class like the example above first and then update your AndroidManifest.xml file as shown below:

<application
    android:name=".MyApplication"
    ...
 
</application

Collection & Link People to Data

The NeuroID SDK provides two collection options:

  • Identify at Start - Use this in scenarios where a unique Identity ID is known at the start of collection (or you have chosen to have the NeuroID SDK generate an identifier that you will store).
  • Identify after Start - Use this in scenarios where a unique Identity ID is not known from the start of collection but will be known shortly after.

Identity ID/User ID Requirements

To connect NeuroID Analytics results to a specific individual applicant, the Identity ID must meet all of the following requirements:

  • It must be the same identifier used to persist an applicant's identity in your own system. You may refer to this as an Application ID, an Applicant ID, a User ID, a Customer ID, or something similar. Regardless, you must set an Identity ID that is unique to the applicant and exists in your own system. This value will be used to call the NeuroID API for signals to join with your internal applicant data.
  • It must be a string value.
  • It must contain only alphanumeric characters, dashes, underscores, or periods.
  • It must be a minimum length of 3 characters.
  • It must be a maximum length of 100 characters.
  • It must not contain any PII such as an email address or passport number.

Single Use-Case Data Collection

In scenarios where there is a single use-case within the app (e.g. Sign Up or Login), choose one of the following collection options.

For Identify at Start sessions, the following commands are relevant:

  • startSession(userID:String, completionCallback: (StartSessionResult) -> Unit)
    • Note: Do not pass a userID if you would like an identifier automatically generated for you.
    • Note: Calling startSession a second time will end the previous session and begin a new one.
  • pauseCollection() - Use this command to temporarily pause the SDK (to avoid collecting sensitive info).
  • resumeCollection() - Use this command if you want to resume from a temporary pause in collection.
// e.g. When a Sign Up button is pressed
NeuroID.getInstance()?.startSession("myIdentityID") {
 println("Session is started: ${it.started} with ID: ${it.sessionID}")
}

// e.g. When a Continue button is pressed that leads to a PII screen
NeuroID.getInstance()?.pauseCollection()


// e.g. When a Continue button is pressed that leads to a screen that should be collected
NeuroID.getInstance()?.resumeCollection()

For Identify after Start sessions, the following commands are relevant:

  • start(completionCallback: (Bool) -> Unit)
    • Note: Calling startSession a second time will end the previous session and begin a new one.
  • setUserID(userID:String)
  • stop()
// e.g. When a Sign Up button is pressed
NeuroID.getInstance()?.start() {
 println("Session is started: $it")
                 
// Optional - Call setUserID immediately after start
 NeuroID.getInstance()?.setUserID("myIdentityID")
}

// e.g. On another page or later in the flow when the Identity ID is known
NeuroID.getInstance()?.setUserID("myIdentityID")

// e.g. When a Submit button is pressed and the session is complete
NeuroID.getInstance()?.stop()

Multi Use-Case Data Collection

In scenarios where there are multiple use-cases within the same app (e.g. Sign Up and Login), rather than calling start or startSession, use the command startAppFlow. This command takes the Site ID of the specific flow and allows the flexibility to Identify at Start or Identify after Start.

// Command API
NeuroID.getInstance()?.startAppFlow(
  siteID:String, 
  userID:String?, 
  completionCallback: (StartSessionResult) -> Unit
)

// Example Usage with Identifier at start
NeuroID.getInstance()?.startAppFlow(
  "form_neuro101",
  "myIdentityID"
) {
 println("Session is started: ${it.started} with ID: ${it.sessionID}")
}

// Example Usage with Identifier after start
NeuroID.getInstance()?.startAppFlow(
  "form_neuro101"
) {

 // it.sessionID will be empty
 println("Session is started: ${it.started} with ID: ${it.sessionID}")
 
 // At a later point (either in this callback or on a different page) call setUserID to set
 // the `identityID`
 NeuroID.getInstance()?.setUserID("myIdentityID")
}

// Example for an additional flow after calling startAppFlow and starting a session
NeuroID.getInstance()?.startAppFlow(
  "form_neuro102"
) {
 
 // it.sessionID will be the previously set ID (either from the previous startAppFlow
 //  or from the setUserID command)
 println("Session is started: ${it.started} with ID: ${it.sessionID}")
}

Android SDK Advance Device Library

NeuroID offers an Advanced Device Library that will collect additional signals.

Installing the Library

Specify the repositories from where the dependencies are going to be resolved.

They could be added either in your app-level build.gradle or in your project level settings.gradle.

App Level Example

// Use this block ONLY for Gradle versions 7 or higher
android {
...
	repositories {
  	...
  	maven { url 'https://maven.fpregistry.io/releases' }
  	maven { url 'https://jitpack.io' }
	}
}

// Use this block ONLY if Gradle version is lower than 7.
allprojects {	
  repositories {
  ...
  maven { url 'https://maven.fpregistry.io/releases' }
  maven { url 'https://jitpack.io' }
}}

Project Level Example

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven { url 'https://maven.fpregistry.io/releases' }
        maven { url 'https://jitpack.io' }
    }
}

Next, add the following dependency to your build.gradle file. To see available versions, visit [Released Versions].

dependencies {
 implementation 'com.github.Neuro-ID:neuroid-android-sdk:android-advanced-device-sdk:vX.X.X'
}

When using the NeuroID Android SDK .aar files locally, the FPJS library must be added explicitly so you'll need to add the following additional dependency to your build.gradle file.

dependencies {
    implementation "com.fingerprint.android:pro:2.5.0"{
        exclude group: 'org.jetbrains.kotlin', module: 'kotlin-stdlib'
    }
}

🚧

Required for mimifyEnabled True Releases.

Add the following ProGuard rule in your Proguard file.

-keep class com.neuroid.** { *; }
-keep class retrofit2.** { *; }
-keep class com.google.gson.** { *; }-keep class com.neuroid.** { *; }

Using the Advanced Device Library

If you set isAdvancedDevice to True when Initializing the SDK, you can skip this section.

To use the Advanced Library in your Android app, import the NeuroID start()method that will enable the Advanced Device Signal capabilities.

import com.neuroid.tracker.extensions.startSession

Then, make the following adjustment to the Android SDK setup instructions above.

  • Locate your NeuroID.getInstance()?.startSession("yourSessionID") command.
  • Replace it with NeuroID.getInstance()?.startSession("yourSessionID", true) or NeuroID.getInstance()?.startSession(nil, true).
    • Passing a true parameter indicates you would like to enable AdvancedDevice tracking
var startedResult = NeuroID.getInstance()?.startSession("yourSessionID", true);
log.d("NeuroID","NeuroID started ${startedResult.started} with session ID ${startedResult.sessionID}");

Android SDK Common Methods

Signal Collection

The NeuroID Mobile SDK silently captures user interactions in a manner that does not block the main thread. All user interactions captured omit any text entered by the user. The SDK never collects sensitive user data.

Examples of Android interactions we capture:

  • Activities/Fragments life cycle: onStart(), onResume(), onPaused(), onDestroyed, onFragmentAttached(), onFragmentDetached()
  • UI widgets/Containers/Views: EditText, Spinner, Button, CheckBox, RadioButton, RadioGroup, Switch, RecyclerView, WebView
  • Events: TOUCH_MOVE, TOUCH_START, TOUCH_END, FOCUS, WINDOW_BLUR, INPUT

Setting the Screen Name

Every time a new screen is presented to the user, use the setScreenName method to associate all captured data with that screen.

Note: It is important to do this after starting the NeuroID SDK and before each screen renders.

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    binding.apply {
        // Your code
        // ...
        try {
        	  NeuroID.getInstance()?.setScreenName("UserDetails")
        } catch (e: Exception) {
            println("NeuroID SDK is not started ${e.message}")
        }
        // ...
    }
}

Marking Attempted Logins

If NeuroID is configured for a login page then use the attemptedLogin command whenever the login is attempted (through button click or biometric). This should be done regardless of login success. Optionally, you can include the attempted userID. See full API documentation. 

NeuroID.getInstance()?.attemptedLogin("myLoginID")

// Identifier Not Required
NeuroID.getInstance()?.attemptedLogin()

Excluding Views

In circumstances where you want to completely exclude a view and its subviews from any signal/event capturing, pass your views to the excludeView function, as shown below.

NeuroID.getInstance()?.excludeViewByResourceID("view_id_string")

Optimizing Your Installation with Field Identifiers

While the NeuroID Mobile SDK installation should already be collecting signals, we recommend one additional step to ensure the best experience when viewing and understanding the data, particularly in the customer portal.

For each input field in your application, we recommend setting a field identifier ( contentDescription attribute (or id field in XML) for Android, accessibilityIdentifier for iOS, or testID/accessibilityLabel attribute for React Native).

The field identifier is used by the SDK in order to name and group interactions.

If you do not set a field identifier the SDK will attempt to do it using fallback placeholders. If no fallback can be found a auto-generated identifier will be assigned.

See examples below.

// progamatically in Kotlin (Android)
textView.contentDescription = "email field"

// in XML layout (Android)
<TextView
        android:id="@+id/textView_description"
        .
        .
        android:contentDescription="email_field"
        .
        .
        app:layout_constraintEnd_toEndOf="parent"/>

Android SDK Next Steps

  • Contact your NeuroID representative to verify your integration is complete.

Troubleshooting

Building the project results in a Kotlin version error:

/Users/test/.gradle/caches/transforms-3/0a4dae3de06fdecb02c8a1df10d15ad8/transformed/jetified-kotlin-stdlib-jdk8-1.5.30.jar!/META-INF/kotlin-stdlib-jdk8.kotlin_module: Module was compiled with an incompatible version of Kotlin. The binary version of its metadata is 1.5.1, expected version is 1.1.16.

Try changing the Kotlin version in the build.gradle file to a version that is >= 1.5.1 (as shown in the example below), then re-sync and rebuild the project.

Example:

Original Kotlin version:ext.kotlin_version = "1.3.72"

Updated Kotlin version: ext.kotlin_version = "1.6.0"

The application fails immediately upon running because of a Coroutine Dispatcher error:

java.lang.NoClassDefFoundError: Failed resolution of: Lkotlinx/coroutines/Dispatchers;

Ensure that you have included the Gradle dispatcher class dependency shown below in your build.gradle file, then re-sync and rebuild the project.

org.jetbrains.kotlinx:kotlinx-coroutines-android:1.5.2

A java.lang.NoSuchMethodError exception occurs during compose operations, causing a crash in your application:

The most likely cause for this issue is that the compose library version(s) specified in your dependencies are getting overridden by a compose version that is included in the NeuroID SDK. The Android NeuroID SDK uses Compose 1.7.3. We've seen situations where customers were using compose 1.4.3, and relied on some methods that were changed in 1.7.x which caused their application to crash. To see if this may be causing your issue:

  • Check your application compose version using the command "./gradlew app:dependencies" to see if this applies to you
  • If it does apply, try excluding and/or forcing a compose library version in your "app/build.gradle" file. It will look something like the following example:
configurations.all {
    resolutionStrategy {
        force "androidx.compose.ui:ui:<compose version to force to>"
        force "androidx.compose.material:material:<compose version to force to>"
        force "androidx.compose.foundation:foundation:<compose version to force to>"
    }
}
dependencies {
  .
  .  
	implementation ("com.github.Neuro-ID.neuroid-android-sdk:android-sdk:<neuroid_sdk>") {
        exclude group: "androidx.compose.ui", module: "ui"
        exclude group: "androidx.compose.ui", module: "ui-util-android"
        exclude group: "androidx.compose.material", module: "material"
        exclude group: "androidx.compose.foundation", module: "foundation"
  }
  .
  .
}

Build conflicts arise due to Kotlin versioning on the Advanced Device dependency.

Add the exclude option in the implementation.

dependencies {
  implementation "com.fingerprint.android:pro:2.3.2"{
        exclude group: 'org.jetbrains.kotlin', module: 'kotlin-stdlib'
    }
}

Updated 2 months ago