Guides

Android SDK <3.3.0

Suggest Edits

SDK Requirements for Versions Prior to 3.3.0

Installation

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

📱
Android Layouts w/Jitpack v3.1.0 to < v3.3.0
Open Recipe
📱
Android Layouts w/Jitpack < v3.1.0
Open Recipe

To see available versions, please visit Release Versions.

Add the NeuroID SDK to the Project

NeuroID offers two options for adding the SDK to a project, either Using Jitpack (preferred) or Manual Installation. Follow the instructions for either option below.

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 Installation

Installing the NeuroID SDK manually requires downloading 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.
// 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 
val neuroIDInstance = NeuroID.Builder(
            this, 
            "form_api_key_development"
        ).build()
       
// Save the singleton instance
NeuroID.setNeuroIdInstance(neuroIDInstance)

// 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 
val neuroIDInstance = NeuroID.Builder(
            this, 
            "form_api_key_development"
        ).build()
       
// Save the singleton instance
NeuroID.setNeuroIdInstance(neuroIDInstance)

// Set the site ID
NeuroID.getInstance()?.setSiteId("form_YOURFORM")

// Set the environment as production or not
// false - declares the environment as development or testing
// true  - declares the environment as production
NeuroID.getInstance()?.setEnvironmentProduction(false)

🚧

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:

Note: These commands are only available in SDK v3.1.0+.

  • startSession(userID:String): StartSessionResult
  • 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()

Identify after Start sessions - the following commands are relevant:

  • start(): Bool
    • 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()

❗️

Required for Setting the Identity ID in SDK v3.1.0 and prior

For SDK versions < 3.1.0 setUserID must be called after calling start.

NeuroID does not start collecting events until after the start method is called. The setUserID method emits an event that is required for a valid session.

The setUserID method will throw an exception in the following cases:

  • Calling setUserID prior to calling the start method.
  • Calling setUserID with an invalid userID string (see Identity ID requirements above).

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 Library

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.start

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

If 3.1.0 - 3.3.0

  • 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.

If prior to 3.1.0,

  • Locate your NeuroID.getInstance()?.start() command.
  • Replace it with NeuroID.getInstance()?.start(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}");

NeuroID.getInstance()?.start(true)

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}")
        }
        // ...
    }
}

❗️

Required for setScreenName in versions 3.1.0 and prior

If your SDK version is prior to 3.1.0,setScreenName must be called after calling start.

NeuroID does not start collecting events until AFTER the start method is called. setScreenName is an event that NeuroID requires to be captured for a valid session.

setScreenName will throw an exception when called prior to calling the start method.


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

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