pwittchen / rxbiometric

☝️ RxJava and RxKotlin bindings for Biometric Prompt (Fingerprint Scanner) on Android

RxBiometric

RxJava and RxKotlin bindings for Biometric Prompt (Fingerprint Scanner) on Android (added in Android 9 Pie, API Level 28+)

If your app is drawing its own fingerprint auth dialogs, you should switch to using the BiometricPrompt API as soon as possible.

It's an official statement from Google Android Developers Blog. RxBiometric helps you to do that via RxJava stream!

Contents

• Usage
• Examples
• Download
• Tests
• Code style
• Static code analysis
• JavaDoc
• Changelog
• Releasing
• Mentions
• References
• License

Usage

Simple library usage in Kotlin looks as follows:

RxBiometric
  .title("title")
  .description("description")
  .negativeButtonText("cancel")
  .negativeButtonListener(DialogInterface.OnClickListener { _, _ ->
    showMessage("cancel")
  })
  .executor(mainExecutor)
  .build()
  .authenticate(context)
  .subscribeOn(Schedulers.io())
  .observeOn(AndroidSchedulers.mainThread())
  .subscribeBy(
    onComplete = { showMessage("authenticated!") },
    onError = { showMessage("error") }
  )

Library also have validation method in the Preconditions class, which you can use to verify if you're able to use Biometric.

Preconditions.hasBiometricSupport(context)

There's also RxPreconditions class, which has the same method wrapped in RxJava Single<Boolean> type, which you can use to create fluent data flow like in the example below

RxPreconditions
  .hasBiometricSupport(context)
  .flatMapCompletable {
    if (!it) Completable.error(BiometricNotSupported())
    else
      RxBiometric
        .title("title")
        .description("description")
        .negativeButtonText("cancel")
        .negativeButtonListener(DialogInterface.OnClickListener { _, _ ->
          showMessage("cancel")
        })
        .executor(mainExecutor)
        .build()
        .authenticate(context)
  }
  .subscribeOn(Schedulers.io())
  .observeOn(AndroidSchedulers.mainThread())
  .subscribeBy(
    onComplete = { showMessage("authenticated!") },
    onError = {
      when (it) {
        is AuthenticationError -> showMessage("error")
        is AuthenticationFail -> showMessage("fail")
        is AuthenticationHelp -> showMessage("help")
        is BiometricNotSupported -> showMessage("biometric not supported")
        else -> showMessage("other error")
      }
    }
  )

If you want to create your own CryptoObject and use it during authentication, then you can call authenticate(context, cryptoObject) method instead of authenticate(context).

Of course, don't forget to dispose Disposable appropriately in the Activity Lifecycle.

Library can be used in the Java projects as well. Idea is the same, just syntax will be a bit different.

Examples

Complete example of the working application can be found in the kotlin-app directory.

Download

You can depend on the library through Gradle:

dependencies {
  implementation 'com.github.pwittchen:rxbiometric:0.1.0'
}

Tests

Tests are available in library/src/test/kotlin/ directory and can be executed on JVM without any emulator or Android device from Android Studio or CLI with the following command:

./gradlew test

Code style

Code style used in the project is called SquareAndroid from Java Code Styles repository by Square available at: https://github.com/square/java-code-styles.

Static code analysis

Static code analysis runs Checkstyle, PMD, Lint and Detekt. It can be executed with command:

./gradlew check

Reports from analysis are generated in library/build/reports/ directory.

JavaDoc

Documentation can be generated as follows:

./gradlew dokka

Output will be generated in library/build/javadoc

JavaDoc can be viewed on-line at https://pwittchen.github.io/RxBiometric/library/

Changelog

See CHANGELOG.md file.

Releasing

See RELEASING.md file.

Mentions

• Android Weekly - issue #324
• Android Weekly China - issue #194
• 30 summertime libraries which you don't want to miss in 2018

References

• https://android-developers.googleblog.com/2018/08/introducing-android-9-pie.html
• https://android-developers.googleblog.com/2018/06/better-biometrics-in-android-p.html
• https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt
• https://github.com/Kieun/android-biometricprompt
• https://android-developers.googleblog.com/2019/10/one-biometric-api-over-all-android.html

License

Copyright 2018 Piotr Wittchen

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

rxbiometric's Issues

Not be able to get AuthenticationResult onComplete

Would be nice be able to use Authenticationresult

Dialog Dismiss

If we tap outside Biometric Dialog it is dismissing. It should remain as it is.

Improve syntax of unit tests

Unit tests in Kotlin could be more concise. Have a look at this: https://github.com/kotlintest/kotlintest.

cancellationSignal is missing

In Readme file, it's mentioned that we can set cancellation signal using cancellationSignal(cancellationSignal), however, it's missing from library.

Release 0.1.0

Release notes:

• used androidx.biometrics to support devices since Android 6 (Marshmallow) - issue #1, PR #9
• removed Preconditions#isAtLeastAndroidPie() method
• removed Preconditions#canHandleBiometric(context) method
• removed RxPreconditions#isAtLeastAndroidPie() method
• removed RxPreconditions#canHandleBiometric(context) method

Things to do:

• bump library version
• upload archives
• close and release artifact
• update JavaDocs on gh-pages
• update CHANGELOG.md
• update version in README.md
• create GitHub release

Consider adding fallback strategy for PrePie devices

Check this: https://github.com/fython/BiometricPromptCompat

Steps for doing this:

• extract code targeted for Android P to one separate class
• hide this class behind the interface and make it default implementation
• create another implementation of the interface using compat code
• choose strategy dynamically depending on Android version
• allow to choose strategy explicitly in the code

Get Callback only once when authenticate finger

Hi,

Device: Gionee A1
OS: 7.0

I try to Authenticate finger print but i get callback only one time.
Click on Authenticate Button.
Dialog pop out.
touch the wrong finger dialog prompt for wrong finger and get callback on failed
2nd time again touch wrong or right finger not get callback in MainActivity subscribeby method

Release 0.0.1

Things to do:

• bump library version
• update JavaDoc on gh-pages
• upload archives to Maven Central Repository
• close and release artifact
• update CHANGELOG.md after Maven Sync
• bump library version in README.md after Maven Sync
• create new GitHub release

Add convenience method for validation to RxBiometric class

Add convenience method for validation to RxBiometric class, so library users won't have to call canHandleBiometric(context) explicitely, flatMap(...) operation can be hidden under the hood and we can throw BiometricNotSupported when needed.

It could look like that in the API:

RxBiometric
  .enableValidation()
  . // rest of the code goes here
  ...

Add gif from demo app to docs

onComplete is not being called

When I try to authenticate via fingerprint, onComplete is being invoked. After that, if I try to authenticate again successfully, onComplete is not being invoked.

Not working on Xiaomi Note 3 running Android 5.1

Runs fine on my Xperia E6883 running 7.1

Error message on the Xiaomi when I tap Authenticate - Error Other

Let me know if you need any particular info.
RxBiometricsLogcat.txt

Issue when try too many failed attempts

Hi,

I try too many failed attempts after that nothing happen when click on Authenticate button

Replace kotlintest with junit tests back again due to incompatibility with Jacoco

Tests written with kotlintest library cannot be used for test coverage report generation for now, so we have to revert them back to JUnit.

Problem was reported in kotlintest project kotest/kotest#398

Broken link on Readme

When I click to view JavaDoc on https://pwittchen.github.io/RxBiometric/library , I get 404 not found error. Seems like the link is broken.

Detect new finger enrollment

Add ability to find out about new finger enrollment

Android biometric hint not translated

this hint "Touch the fingerprint sensor" is not translated when we change the language of the phone , can you please check it

New release missing

Although latest source code uses androidx.biometric:biometric:1.0.1, library's latest release is 0.1.0 which uses androidx.biometric:biometric:1.0.0-alpha03. When will you make new release which uses stable version of biometric library?