Add the biometrics authentication SDK to your Android app

Learn how to add the biometric authentication software development kit (SDK) to your Android or iOS app so you can test biometric authentication during your manual and automated test sessions.

Before you start

You’ll need to:

Add KobitonBiometric.aar

First you’ll open your app’s Android Studio project and create a libs directory inside your project’s app directory if you don’t already have one. Then download and move KobitonBiometric.aar into your new libs directory.

Modify build.gradle

Next you’ll open the build.gradle in your app directory and add our library (or all your .aar libraries) to your list of dependencies:

    implementation fileTree(dir: 'libs', include: ['<library>']) // Replace <library> with KobitonBiometric.aar or *.arr.
groovy
Example
dependencies {
    implementation fileTree(dir: 'libs', include: ['KobitonBiometric.aar']) // Alternatively, replace KobitonBiometric.aar with *.arr to include all libraries.
    implementation 'org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version'
    implementation 'androidx.core:core-ktx1.3.0'
    implementation group: 'com.google.android.material', name: 'material', version: '1.3.0-alpha01'

    testImplementation 'junit:junit:4.13'

    androidTestImplementation 'androidx.test.ext:junit:1.1.1'
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'

}
groovy

When you’re finished, save your file.

Modify AndroidManifest. xml

Next you’ll open the AndroidManifest.xml file in /app/src/main and add the following lines to your <manifest> element:

<uses-permission android:name="android.permission.USE_BIOMETRIC" android:requiredFeature="false"/>
<uses-permission android:name="android.permission.INTERNET"/>
xml

Locate your <application> element and add the following line:

android:usesCleartextTraffic="true"
xml

Inside <application>, replace:

  • *.BiometricManager classes with com.kobiton.biometric.BiometricManager

  • *.BiometricPrompt with com.kobiton.biometric.BiometricPrompt

Example
$EXAMPLE$
xml

When you’re finished, save your file and verify your changes.

Verify your changes

First, rebuild your .apk and upload it to the app repository. Then, start a manual test session, launch your app, and try using biometric authentication to sign in. Select Pass and check the logs to verify your changes.

Known issues

If you add our library to your app and send BiometricPrompt.AuthenticationCallback during authentication using toasts, your app may crash during your test session. If this happens, you’ll find the following error in your crash logs:

java.lang.NullPointerException: Can't toast on a thread that has not called Looper.prepare()
java

Here’s a script that could lead to a crash:

private BiometricPrompt.AuthenticationCallback getAuthenticationCallback() {
    return new BiometricPrompt.AuthenticationCallback() {
        @Override
        public void onAuthenticationError(int errorCode, @NonNull CharSequence errString) {
            Toast.makeText(MainActivity.this, "Authentication error", Toast.LENGTH_SHORT).show();
            super.onAuthenticationError(errorCode, errString);
        }

        @Override
        public void onAuthenticationSucceeded(@NonNull BiometricPrompt.AuthenticationResult result) {
            Toast.makeText(MainActivity.this, "Authentication successful", Toast.LENGTH_SHORT).show();
            super.onAuthenticationSucceeded(result);
        }

        @Override
        public void onAuthenticationFailed() {
            Toast.makeText(MainActivity.this, "Authentication failed", Toast.LENGTH_SHORT).show();
            super.onAuthenticationFailed();
        }
    };
}
java