1. Introduction¶

BCC Finger is a library meant to be integrated into an iOS application from a .framework file. It uses the device’s camera to take a picture of fingerprints for biometric purposes.

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

1.1. Requirements¶

Git
Cocoapods, available at https://cocoapods.org/.

2. Installation¶

2.1. Installing Dependencies¶

1 - Add the following Pods to the application dependencies on Podfile:

pod 'lottie-ios'

Note

If the application does not possess a Podfile, it can be created in the root folder of your Xcode project using the command pod init in the terminal.

It is preferable to use dynamic frameworks. It can be indicated using the flag use_frameworks! on Podfile.

A Podfile example with a target called BCCs-Sample is shown below:

target 'BCCs-Sample' do
  use_frameworks!

  pod 'lottie-ios', '~> 3.3.0'
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
    end
  end
end

Important

It is recommended to use the minimum supported iOS version for your application as the same of this framework: iOS 13.0, as the example above.

2 - Close your Xcode project and open at the terminal the folder where is your Podfile, then execute:

$ pod install

After the execution finishes, a file with .xcworkspace extension will be created in the same folder.

3 - Open the new .xcworkspace file.

Warning

From now on, every time the user wants to open the project, it is necessary to open it through this .xcworkspace file, as it includes the dependencies.

2.2. Importing and Configuring¶

2.2.1. Importing the Project¶

Open the project using the .xcworkspace file.
Add the FingerPhoto.framework file to the project, then add it to the framework list of your application.
- Move the .framework file to the project file tree.
  
  If there’s already a framework folder, it is recommended to move the file to there.
- Open the project settings.
- Go to General tab.
- Click and drag the .framework to the project tree under the section “Frameworks, Libraries, etc.”
Change the BCCFinger.framework setting from “Do not embed” to “Embed & Sign”.
Change the target version of your project to a minimum of iOS 13.

Note

It is recommended to disable iPad as a target.

2.2.2. Initial Configuration¶

This version does not have dependencies on Firebase, either from an initial configuration called by AppDelegate. The only initial configuration needed is that the application must request camera use permission. To do so, add the following key in the info.plist file, at Information Property List:

Privacy - Camera Usage Description

The key value is a message to be exhibited to the user when requesting camera use permission. This value can be blank or filled with the desired message.

3. Usage¶

3.1. Parameters and Constructor¶

A simple library usage example is shown below:

// To initialize a new capture
BCCFingerBuilder(self, delegate: self).initializeCapture()

The BCCFingerBuilder class takes the following parameters:

hostVC: UIViewController - View controller that calls the capture screen.
delegate: BCCFingerDelegate - Interface responsible for notifying capture events (e.g. failure or success).

The initialize method also accepts an optional parameter, ans shown below:

public func initializeCapture(
    _ navController: UINavigationController? = nil
) { ... }

If you want the navigation to run through a navigation controller, you must provide it when calling the method.

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: Bool) - Enables the option to skip the current capture.
setDebugMode(_ enable: Bool) - Enables debug mode.
buildCaptures(_ captures: BCCFingerCaptureType) - Defines the fingerprint capture type. The options are:
```
public enum BCCFingerCaptureType {
    case BOTH_HANDS
    case ONLY_LEFT_HAND
    case ONLY_RIGHT_HAND
    case THUMBS
    case LEFT_THUMB
    case RIGHT_THUMB
    case FULL_HANDS
    case FULL_LEFT_HAND
    case 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 thumbs.
- FULL_RIGHT_HAND - Right hand only, with thumbs.
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:

var skipsHandOption: Bool = false
var debugMode: Bool = false
var capture: BCCFingerCaptureType = .FULL_HANDS
var beginDelaySeconds: Float = 1
var minQuality: Int = 20
var maxQuality: Int = 80
var totalTime: Double = 30
var stepCount: Int = 30

3.2. Return Values¶

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

func fingerCaptureDidFinish(
    _ returnData: BCCFingerReturnData,
    analytics: BCCFingerAnalytics
)

The returnData object contains the following methods for data retrieval:

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

public enum FingerIndex: Int {
    case leftLittle = 0
    case leftRing = 1
    case leftMiddle = 2
    case leftIndex = 3
    case leftThumb = 4
    case rightThumb = 5
    case rightIndex = 6
    case rightMiddle = 7
    case rightRing = 8
    case rightLittle = 9
}

getCapturedFingers() - Returns a map that relates the finger indexes to the captured biometrics.
getCapturedFingersData() - Returns the list of all fingerprints captured:
```
public var fingerprintPNG: UIImage
public var wsqAsBase64: String
```
- fingerprintPNG - 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:

public class BCCFingerReturnData {
    public let leftHand: HandData?
    public let rightHand: HandData?
}

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

The HandData class contains the following information:

public internal(set) var capturedFingers: [FingerIndex : FingerData] = [:]
public internal(set) var skippedFingers: [FingerIndex] = []
public internal(set) var handsPhoto: UIImage? = nil
public internal(set) var thumbsPhoto: UIImage? = nil

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:

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

3.3. Sample Project¶

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

import UIKit
import FingerPhoto
import BCCFinger

class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func startCaptureAction(_ sender: UIButton) {
        BCCFingerBuilder(self, delegate: self)
            .initializeCapture()
    }
}

extension ViewController: BCCFingerDelegate {

    func fingerCaptureDidFinish(
        _ returnData: BCCFinger.BCCFingerReturnData,
        analytics: BCCFinger.BCCFingerAnalytics
    ) {
        // ...
    }

    func didAbortFingerCapture(
        analytics: BCCFinger.BCCFingerAnalytics
    ) {
        // ...
    }

}