1. Introduction¶

BCC Finger is an Android library meant to be integrated into an Android application. Essentially, it will open a camera and capture fingerprints for biometric purposes.

This Manual is updated for BCC Finger Photo Android version 4.3.0.

1.1. Requirements¶

BCC Finger Photo is an Android library and must be imported into the target project.

Minimum Android Version: Android 6.0 (SDK 23), “Marshmallow”.
Minimum kotlin version: 1.6.0.
Mobile device must have a camera.
Native app must be built with Android technology.
Development environment: An Android IDE is required, such as Android Studio (recommended)
Additional external dependencies:
- Lottie, version 3.0.0

2. Installation¶

2.1. Adding the Library in the App Project¶

The BCC Finger Photo library requires JNA for Android. Both are provided by Griaule as .aar files.

To add the libraries, go to your project directory, open the app folder and create the following directories libs/bccfinger. Then, add the jna.aar and the bccfingerphotolib-release.aar dependencies. The folder structure must be similar to this:

../../../_images/fingerFolderStructure.png

The next step is to make these files visible to the gradle dependencies. To do this, add the following line in the file build.gradle (:app) in the dependencies object:

dependencies {
  [...]
  implementation fileTree(dir: 'libs/bccfinger', include: ['*.aar'])
}

Inside the build.gradle (:app) file, also add the compile options and set set Source Compatibility and Target Compatibility to use 1.8 (Java 8):

compileOptions {
  sourceCompatibility = 1.8
  targetCompatibility = 1.8
}

2.2. Setting All Dependencies¶

Make the changes below to the file android/app/build.gradle:

dependencies {
  // YOUR DEPENDENCIES //
  ...

  // BCC FINGER //
  implementation fileTree(dir: 'libs/bccfinger', include:['*.aar'])

  // ANDROIDX //
  implementation 'androidx.appcompat:appcompat:1.1.0'
  implementation 'androidx.constraintlayout:constraintlayout:1.1.3'
  implementation 'com.google.android.material:material:1.1.0'

  // LOTTIE //
  implementation 'com.airbnb.android:lottie:3.0.0'

  // CAMERA X //
  def camerax_version = "1.2.0-rc01"
  // CameraX core library using camera2 implementation
  implementation "androidx.camera:camera-camera2:$camerax_version"
  // CameraX Lifecycle Library
  implementation "androidx.camera:camera-lifecycle:$camerax_version"
  // CameraX View class
  implementation "androidx.camera:camera-view:$camerax_version"
}

3. Usage¶

3.1. Parameters and Constructor¶

A simple library usage example is shown below:

// To initialize a new capture
BCCFingerBuilder(this, this).initializeCapture()

The BCCFingerBuilder class takes the following parameters:

context:Context - The application context.
delegate:BCCFingerDelegate - Interface responsible for notifying capture events (e.g. failure or success).

The BCCFingerBuilder class is responsible for handling the usage configuration for BCCFinger. The following parameters are accepted for configuring biometric capture and software behaviour:

setSkipCaptureOption(enable: Boolean) - Enables the option to skip the current capture.
setDebugMode(enable: Boolean) - Enables debug mode.
buildCaptureType(type: [BCCFingerPhotoCaptureType]() - Defines the fingerprint capture type. The options are:
```
enum class BCCFingerPhotoCaptureType {
    BOTH_HANDS,
    ONLY_LEFT_HAND,
    ONLY_RIGHT_HAND,
    THUMBS,
    LEFT_THUMB,
    RIGHT_THUMB,
    FULL_HANDS,
    FULL_LEFT_HAND,
    FULL_RIGHT_HAND;
}
```
- BOTH_HANDS - Both hands without thumbs.
- ONLY_LEFT_HAND - Left hand only, without thumbs.
- ONLY_RIGHT_HAND - Right hand only, without thumbs.
- THUMBS - Both thumbs.
- LEFT_THUMB - Left thumb only.
- RIGHT_THUMB - Right thumb only.
- FULL_HANDS - Both hands with thumbs.
- FULL_LEFT_HAND - Left hand only, with thumb.
- FULL_RIGHT_HAND - Right hand only, with thumb.
buildBeginDelaySeconds(delay: Float) - Defines the delay to start threshold auto adjustment.
buildThreshold - Defines threshold parameters.

For reference, the full list of parameters and default values is:

skipsHandOption: Boolean = false
debugMode: Boolean = false
beginDelaySeconds: Float = 2f
maxQuality: Int = 50
minQuality: Int = 0
totalTime: Float = 20f
stepCount: Int = 20
captureType: BCCFingerPhotoCaptureType = BCCFingerPhotoCaptureType.FULL_HANDS

3.2. Return Values¶

The results from the last fingerprint capture can be retrieved through the fingerCaptureDidFinish method from the BCCFingerDelegate interface:

fun fingerCaptureDidFinish(
    returnData: BCCFingerReturnData,
    analytics: BCCFingerReturnAnalytics
)

The returnData object contains the following methods for data retrieval:

getCapturedFingersIndexes() - Returns a list with the index of all captured fingerprints:

enum class BCCFingerIndex(val index: Int) {
    leftLittle(0),
    leftRing(1),
    leftMiddle(2),
    leftIndex(3),
    leftThumbs(4),
    rightThumbs(5),
    rightIndex(6),
    rightMiddle(7),
    rightRing(8),
    rightLittle(9);
}

getCapturedFingers() - Returns a map that relates the finger indexes to the captured biometrics.
getCapturedFingersData() - Returns the list of all fingerprints captured:
```
data class BCCFingerData(
    var fingerprintImage: Bitmap,
    var wsqAsBase64: String?
)
```
- fingerprintImage - PNG image of the fingerprint in grayscale.
- wsqAsBase64 - base64 encoded WSQ image of the fingerprint.
getSkippedFingers() - Returns the index list of all skipped finger captures.

The BCCFingerReturnData class also contains attributes that store the capture information grouped by hand:

class BCCFingerReturnData {
    val leftHand: BCCHandData?
    val rightHand: BCCHandData?
}

These attributes can be null whenever captures are not requested for any of the hands.

The HandData class contains the following information:

var capturedFingers = mutableMapOf<BCCFingerIndex, BCCFingerData>()
private set

var skippedFingers = mutableListOf<BCCFingerIndex>()
private set

var handsPhoto: Bitmap? = null
private set

var thumbsPhoto: Bitmap? = null
private set

capturedFingers - Map that relates the finger index to the fingerprint image.
skippedFingers - Index list of all skipped finger captures.
handsPhoto - Original photo of the hand from which the fingerprints were extracted.
thumbPhoto - Original photo of the thumb.

If the user aborts the capture, closing before capturing the biometrics, the method fingerCaptureDidAbort will be called. You can implement this method to treat this scenario.

3.2.1. Retrieving Original Images¶

It is possible to get the original images through the BCCFingerReturnData class, as shown below:

val leftSlapPhoto = returnData.leftHand?.handsPhoto
val rightSlapPhoto = returnData.rightHand?.handsPhoto
val leftThumbPhoto = returnData.leftHand?.thumbsPhoto
val rightThumbPhoto = returnData.rightHand?.handsPhoto

3.3. Sample Project¶

This is a functional sample project for a fingerprint capture using BCC Mobile Finger Android:

package com.example.bccfignerexample

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.example.bccfignerexample.databinding.ActivityMainBinding
import com.griaule.bccfingerphotolib.analytics.   BCCFingerReturnAnalytics
import com.griaule.bccfingerphotolib.fingerApi.declaration.   BCCFingerBuilder
import com.griaule.bccfingerphotolib.fingerApi.declaration.   BCCFingerDelegate
import com.griaule.bccfingerphotolib.fingerApi.returnData.   BCCFingerReturnData


class MainActivity : AppCompatActivity(), BCCFingerDelegate {

    private lateinit var binding: ActivityMainBinding

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        binding = ActivityMainBinding.inflate(layoutInflater)
        setContentView(binding.root)

        setupListeners()
    }

    private fun setupListeners() {
        binding.startCaptureButton.setOnClickListener {    startCapture() }
    }

    private fun startCapture() {
        BCCFingerBuilder(this, this).initializeCapture()
    }

    override fun fingerCaptureDidAbort(
        analytics: BCCFingerReturnAnalytics
    ) {
        // ...
    }

    override fun fingerCaptureDidFinish(
        returnData: BCCFingerReturnData,
        analytics: BCCFingerReturnAnalytics
    ) {
        // ...
    }

}