Before testing an Android app with biometrics authentication in a Kobiton manual or automation session, the app must be updated to use a Kobiton custom biometrics library.

This guide details the steps to alter your app to include Kobiton's custom biometrics library. 

Prepare project code

The current Kobiton custom biometrics library has the following limitations:

• Only Android devices with Android 9 or higher are supported
• Only authentication methods with lower security work:
  
  • authenticate (Android Platform libraries)
  • authenticate (Android Jetpack libraries)
• Authentication with BiometricPrompt.CryptoObject is not supported. The more secure authentication methods below will not work:
  • authenticate with CryptoObject (Android Platform libraries)
  • authenticate with CryptoObject (Android Jetpack libraries)
• FingerprintManager authenticate method, a now deprecated method in API level 28, is not verified to work.

If the app to be integrated is using the unsupported authentication methods above, developers can make use of build variants to create a Kobiton test variant of the app that circumvent CryptoObject.

Biometrics authentication with Kobiton

NOTE: Biometrics authentication does NOT need to be setup on the physical device in order to test an app requiring biometrics through the Kobiton Portal.

Make sure the project code has been prepared accordingly.

Download KobitonBiometric.aar. Create a new folder libs under <project_folder>/app, where <project_folder> is the root folder of the Android project to be altered. Copy the downloaded file into the newly created folder.

Under <project_folder>/app, edit the build.gradle file and add the following line under dependencies:

implementation fileTree(dir: 'libs', include: ['*.aar'])

Perform a project sync to update the changes.

Under <project_folder>/app/src/main, edit the AndroidManifest.xml file and add the following lines:

• Under manifest, add:
  

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

• Under application, add:

  android:usesCleartextTraffic="true"

Below is a sample of the above file after changes are made:

Replace the text in the project code as follows:

• Replace "android.hardware.biometrics.BiometricManager" or "androidx.biometric.BiometricManager" with "com.kobiton.biometric.BiometricManager"
• Replace "android.hardware.biometrics.BiometricPrompt" or "androidx.biometric.BiometricPrompt" with "com.kobiton.biometric.BiometricPrompt"

Save the changes. You may now test the app through the Kobiton Portal.

To learn more about using biometrics authentication during Kobiton manual or automation sessions. see the the main biometrics help page.

Known issue with toasts

The below Java code example illustrates an app using toasts to notify the user about BiometricPrompt.AuthenticationCallback's results:

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();
        }
    };
}

When integrating the Kobiton custom biometric library and running on Kobiton devices, examples like the above code will cause the app to crash with the following exception:

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

This is a known issue that will be addressed in a future Kobiton release. As a temporary solution, use an alternative way to notify the user, such as the following:

• Try snackbar if the app is in the foreground
• Try notification if the app is in the background