Finger Capture 

Introduction 

Overview 

Human finger ridges are acknowledged as detailed, difficult to alter, nearly unique, and durable over the life of an individual. The probability of two people having the same fingerprints is near 1 in 64,000,000,000. This makes finger ridges good long-term markers for human identity.

Capture SDK offers an opportunity to apply this feature for easy authentication, or even identification, in everyday life, using any modern Android or iOS smartphone equipped with a standard camera. Capture SDK is a software library which can be used for scanning fingerprints.

Capture SDK features:

• fingerprints acquisition resulting in raw images of finger ridges, which can be even converted into worldwide WSQ¹ format with a built-in converter
• extracting biometrics data
• storing biometrics data
• comparing biometrics data in order to authenticate (1:1) or identify (1:N)

Once the biometrics data is extracted, fast authentication mode can be utilized, shortening the process so that it encompasses fingerprints acquisition and authentication only.

Architecture 

The library consists of five main components:

• FingerCaptureHandler - responsible for performing the capture. It handles a camera, so there's no need to handle the system camera's API. The component receives the camera stream, analyzes chosen frames, and pushes the camera stream to the preview component. During callbacks, it's possible to retrieve information about the status of the capture and its result.
• LicenseManager - responsible for license management. An activated license is needed in order to use the SDK.
• MatcherHandler - a component which can be used for extracting biometrics data from raw images. Moreover, it is possible to compare biometrics data against other sets of data already available.
• BIOStore - a group of static methods which can be used for storing biometrics data.
• ImageUtils - a bundle of methods which can be used for image processing. The SDK provides a result of a capture in the form of raw images (SDK's internal format). It's essential to use ImageUtils to convert the raw format into another, one that is commonly used: WSQ¹, JPEG² or JPEG2000³.

Variants 

Capture SDK comes in six different variants. Finger modality is present in three of them: Full SDK, Biometry and Finger.

1. Full SDK - It contains all the features of the SDK. Includes components: LicenseManager, FaceCaptureHandler, FingerCaptureHandler, BioMatcherHandler, BioStoreDB, DocumentCaptureHandler, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK'.

2. Biometry variant - It contains all biometric features including face and finger capture and also biometric coding and matching used for liveness checking. Includes components: LicenseManager, FaceCaptureHandler, FingerCaptureHandler, BioMatcherHandler, BioStoreDB, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK-biometry'.

3. Document variant - It contains only document capture features. Includes components: LicenseManager, DocumentCaptureHandler, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK-document'.

4. Finger variant - It contains only finger capture features including biometric coding and matching used for finger liveness checking. Includes components: LicenseManager, FingerCaptureHandler, BioMatcherHandler, BioStoreDB, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK-finger'.

5. Face variant - It contains only face capture features without biometric coding and matching, so for liveness checking you need to use external server. Offline liveness checking is not available. Includes components: LicenseManager, FaceCaptureHandler, BioStoreDB, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK-face'.

6. Face+document variant - It contains only face capture features without biometric coding and matching, so for liveness checking you need to use external server. Offline liveness checking is not available. Additionally it contains also document capture features. Includes components: LicenseManager, FaceCaptureHandler, BioStoreDB, DocumentCaptureHandler, ImageUtils. You can integrate it into your project by specifying it in your Podfile: pod 'BiometricSDK-face_document'.

Integration guide 

Prerequisites 

The integration shall be done by developers with knowledge of:

• Xcode
• Swift or Objective-C
• iOS platform
• (optional) CocoaPods

The required tools are:

• Xcode (with support for iOS 15.0 deployment target or higher)
• iOS device (simulator is not supported)

Installation 

We serve our artifacts with from Artifactory. As an integrator you can choose one the methods of adding our framework to your project:

• using CocoaPods
• manually

CocoaPods

Our CocoaPods distribution method uses cocoapods-art plugin, so you need to install it by adding to your Gemfile or running the following command:

Shell
1gem install cocoapods-art

1. The plugin uses credentials stored in .netrc file.

Netrc
1machine mi-artifactory.otlabs.fr
2login ##USERNAME##
3password ##PASSWORD##

2. Once credentials are present in .netrc, add our repo to your CocoaPod's dependency management system:

Shell
1pod repo-art add smartsdk "https://mi-artifactory.otlabs.fr/artifactory/api/pods/smartsdk-ios-local"

3. At the top of your project Podfile add:

Ruby
1plugin "cocoapods-art", sources: [
2    "smartsdk" # so it could resolve BiometricSDK dependency
3    "master", # so it could resolve dependencies from master repo (the main one), for newer CocoaPods (1.10+) versions it may not be needed anymore
4]

4. Add a variant of Capture SDK in your Podfile:

Ruby
1pod "BiometricSDK" # Full version of the SDK, contains biometrics & documents features
2pod "BiometricSDK-biometry" # Contains only biometrics (finger+face) features
3pod "BiometricSDK-finger" # Contains only finger features
4pod "BiometricSDK-face" # Contains only face features without internal liveness checking mechanism
5pod "BiometricSDK-document" # Contains only document features
6pod "BiometricSDK-face_document" # Contains only face features without internal liveness checking mechanism & documents features

5. Install dependencies with CocoaPods:

Shell
1pod install

Note: If you are already using our repo, and you cannot resolve some dependency, try to update the specs:

Shell
1pod repo-art update smartsdk

Manual installation

1. Download the artifact manually from the artifactory (reference list)
2. In the project editor, select the target to which you want to add a library or framework.
3. Click Build Phases at the top of the project editor.
4. Open the Embedded Binaries.
5. Click the Add button (+).
6. Click the Add Other button below the list.
7. Add the following items:
   • BiometricSDK.framework
   • (optionally for face capture) BiometricSDKFaceCapturePluginNormal.framework (or other face capturing plugin)
   • (optionally for face capture) BiometricSDKAlgorithmPlugin_F6_5_LOW70.framework (or other matching algorithm plugin)
   • (optionally for finger capture new API) FingerCaptureSDK.framework
   • (optionally for finger capture new API) BiometricSDKUIFinger.framework

Manual download list

SDK Size

Analytics 

Capture SDK offers a logging mechanism that collects analytics data about SDK usage and sends this data to IDEMIA's server in the EU. This data helps IDEMIA to improve Capture SDK and the likelihood of integrator success within the app. It is strongly recommended to use the analytics mechanism.

• Sending analytics data is enabled by default.
• You can enable or disable sending analytics data.
• You can choose to send analytics data only when you are connected to a Wi-Fi network, so as not to not use your cellular connection.
• Analytics data that IDEMIA collects contains only technical data.
• No sensitive personal data is collected.
• IDEMIA does not collect any images.

Analytics data that we collect include following information:

• Application name, bundle id, version
• Capture SDK and RemoteLogger libraries versions
• Capture SDK plugins versions
• Device model and operating system version
• Technical information about performed face, finger, and document capture (such as: used capture mode; timestamp; reason of error; time needed to perform a capture; quality of captured image; and light condition)
• Technical information about performed authentication and identification events (such as: used threshold, duration, and obtained score)
• Other technical information (such as: image compression, occurred errors, and SDK performance) that does not contain personal data

You can disable analytics reporting using the appropriate SDK method.

Analytics are enabled by default and data is sent through Wi-Fi and cellular connections to IDEMIA's server in Europe. You can switch to the server in US by calling:

Objective-C
1[[BIORemoteLogger sharedInstance] setConfiguration:[BIORemoteLoggerConfiguration defaultUS]];

You can switch to Wi-Fi only mode with:

Objective-C
1[BIORemoteLogger sharedInstance].wifiOnly = YES;

You can disable analytics as with:

Objective-C
1[BIORemoteLogger sharedInstance].loggerDisabled = YES;

You should perform above calls before using the SDK, for example, in your app delegate.

License Manager 

Remember: A valid license is required before using any feature of the SDK.

To have a valid license:

1. Obtain an instance of LicenseManager via provideLicenseManager() method.
2. Call activate() method on it.

Before Starting

Note: If you use the debug LKMS server without a SSL connection, you should add permission for the arbitrary loads in the transport security section in your Info.plist file. But it's highly recommended NOT to set this permission without the reason.

XML
1<key>NSAppTransportSecurity</key>
2	  <dict>
3		    <key>NSAllowsArbitraryLoads</key>
4		    <true/>
5	</dict>

New license manager

The License manager is the main entry point to use the SDK. You can manage licenses through LicenseManager.

Note: A valid license is required before using any feature of the SDK.

provideLicenseManager

This static method provides an instance of LicenseManager with a predefined LKMS profile. Any interaction with LicenseManager must be executed before starting capture.

Swift
1let manager = LicenseManager.provideLicenseManager(profileId: LkmsProfileId, apiKey: LkmsApiKey, serverUrl: lkmsUrl)

Activating license

This method fetches the license if it's not locally stored and activates it. Additionally, in cases where the license has expired, the function retrieves a new license. This process is crucial and must occur each time the application starts.

Callback solution:

Swift
1manager.activate { (error: LicenseActivationError) in
2        if let error {
3            // Failed to fetch or activate the license.
4        } else {
5            // License fetched and activated with success.
6        }
7    }

Async solution:

Swift
1let result: Result<Void, LicenseActivationError> = await manager.activate()
2    switch result {
3        case .success:
4            // License fetched and activated with success.
5        case .failure(let error):
6            // Failed to fetch or activate the license.
7    }

LicenseActivationError

This is the information about why the license can not be activated.

ActivationErrorType

Development issues

The LKMS license on your device may become invalidated when switching between debug and App Store (also TestFlight) builds of your app. To have a valid license, uninstall the app first and then switch to debug / App Store build. There is no need to uninstall the app when updating the app from the same source (debug build replaced with debug build or App Store build replaced with App Store build). In the SDK there is dedicated error for this: licenseSignatureVerificationFailed.

Integration 

The main component responsible for fingerprint images acquisition is FingerCaptureHandler. This component handles the whole scanning process including the system's camera API. In order to scan fingerprints an end-user needs to show their fingers in a camera sight. The handler processes the camera stream and as a result returns captured images.

1. Import the framework header to your view controller.

Objective-C
1#import <BiometricSDK/BiometricSDK.h>

2. Add at least one UIImageView or subclasses to your layout. It will be used to preview the stream from your camera. It is not necessary for the capture to have a preview.

Objective-C
1@property (weak, nonatomic) IBOutlet UIImageView *preview;

3. Check your license status here.

4. You also need to have the property for FingerCaptureHandler. This object is handling all operations related to capturing.

Objective-C
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2        self.captureHandler = captureHandler;
3        ...
4    }];

5. Set the delegate for FingerCaptureHandler to self. self will have to implement the FingerCaptureHandlerDelegate protocol.

Objective-C
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2        self.captureHandler = captureHandler;
3        self.captureHandler.delegate = self;
4        ...
5      }];

6. After FingerCaptureHandler finished its initialization, the preview view can be set.

Objective-C
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2          self.captureHandler = captureHandler;
3          self.captureHandler.delegate = self;
4          self.captureHandler.preview = self.preview;
5          ...
6        }];

7. Now it can start capturing.

Objective-C
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2            self.captureHandler = captureHandler;
3            self.captureHandler.delegate = self;
4            self.captureHandler.preview = self.preview;
5            [self.captureHandler startCaptureWithCompletionHandlerError:nil];
6        }];

8. Whenever the view controller disappears, resources (e.g. camera) need to be released.

Objective-C
1- (void)viewDidDisappear:(BOOL)animated{
2          [super viewDidDisappear:animated];
3          [self.captureHandler destroy];
4        }

Capture Options

FingerCaptureHandler is created using the set of options it contains. This set of options is represented by FingerCaptureOptions class.

It can be created with one of the available modes. For standard fingerprint acquisition FingerCaptureModeFingers mode should be used.

Once options object is created it's possible to set rest of options:

Lifecycle

FingerCaptureHandler consumes a lot of resources including a camera's resource, which is why it's very important to manage its lifecycle properly. It's recommended to create FingerCaptureHandler when is about to be used and release it when it's no longer needed.

Delegate Protocol

The SDK uses the delegate pattern. The updates about the scanning process are passed through the FingerCaptureHandlerDelegate's methods:

Execution Flow

Fingerprints acquisition Implementation

1. Point where the class is from at the top of the class when using a component where the FingerCaptureHandler is used:

Swift
Objective-C
1    import BiometricSDK

2. Add at least one UIImageView or subclass to the layout. The FingerCaptureHandler handles and wraps the system's camera API. It displays a preview using UIImageView. It is not necessary for the capture to have a preview.

Swift
Objective-C
1    @IBOutlet private var preview: UIImageView!

3. Add a property for holding the strong reference to FingerCaptureHandler, so it won't be released by ARC accidentally.

Swift
Objective-C
1    private var captureHandler: FingerCaptureHandler!

4. Implement delegate methods, so it'll be possible to have a result of the capture.

Swift
Objective-C
1    extension ViewController: FingerCaptureHandlerDelegate {
2        func capturedFingers(_ matchingImages: [BIOImage]?, withImagesToDisplay imagesToDisplay: [FingerImagePreview]?, with result: FingerCaptureResult?, withError error: Error?) {
3            guard let matchingImages, !matchingImages.isEmpty, error == nil else {
4                // Capture failed.
5                return
6            }
7            // Capture finished successfully.
8            // Use `matchingImages` for matching purposes.
9            // Use `imagesToDisplay` for display purposes.
10        }
11        //...
12    }

5. Create FingerCaptureHandler instance and assign the reference to the property:

Swift
Objective-C
1    BIOSDK.createFingerCaptureHandler(with: options) { [weak self] captureHandler, error in
2        self?.captureHandler = captureHandler
3        // ...
4    }

6. Set the delegate for FingerCaptureHandler to self. The self object shall implement FingerCaptureHandlerDelegate protocol.

Swift
Objective-C
1    BIOSDK.createFingerCaptureHandler(with: options) { [weak self] captureHandler, error in
2        self?.captureHandler = captureHandler
3        self?.captureHandler.delegate = self
4        // ...
5    }

7. Set the preview:

Swift
Objective-C
1    BIOSDK.createFingerCaptureHandler(with: options) { [weak self] captureHandler, error in
2        self?.captureHandler = captureHandler
3        self?.captureHandler.delegate = self
4        self?.captureHandler.preview = self?.preview
5        // ...
6    }

8. After the FingerCaptureHandler finished its initialization, the capturing can be stared by calling:

Swift
Objective-C
1    self.captureHandler?.startCapture(completionHandler: nil)

9. Once the FingerCaptureHandler is no longer needed, release it:

Swift
Objective-C
1    self.captureHandler?.destroy()

Result

As a result of fingerprints acquisition, you receive an array of BIOImage objects and a FingerCaptureResult object.

BIOImage

This object represents an image of a fingerprint. It can be converted into worldwide WSQ format commonly used for compressing fingerprint images with a built-in converter as below:

Swift
Objective-C
1let wsqImage = bioImage.dataByCompressingImage(toWSQRatio: 12, withScannerBlack: 0, andScannerWhite: 255)

If you need to show the image on screen, you can convert it to a UIImage:

Swift
Objective-C
1let uiImage = UIImage(from: bioImage)

FingerCaptureResult

This object contains additional information about the capture. Most importantly, it contains information about the liveness check result. If returned, the liveness status is BIOLivenessResultStatusLive, meaning that captured fingers belong to a real person, otherwise it means that captured fingers could have been scanned, for example from a printed photocopy.

Fast Authentication 

Fast authentication mode is a special type of capture mode used only for authentication of an end-user that was previously enrolled. During the enrollment process, it's possible to obtain BIOTemplate objects. The BIOTemplate objects are reference templates that represent captured fingerprints and can be later used for authentication.

One day of performing an authentication is to capture the fingerprints of an end-user in the same way as it's done during the enrollment process and then manually compare the BIOTemplate objects to those obtained during the enrollment. However, that could take longer as the standard finger capture can take up to few seconds. In fast authentication mode it's possible to provide those reference templates before a capture is started while the SDK searches for a match specifically only with those templates, which is a much faster process.

Execution Flow

Below is the generic execution flow to perform a fast authentication. First, the reference templates of the end-user that should be authenticated need to be provided in FingerCaptureOptions to the FingerCaptureHandler. With those, the FingerCaptureHandler will capture the fingerprints and compare them with the reference templates until it has a match. When this happens, the FingerCaptureHandler will return the result. If this doesn't happen and the timeout value is exceeded, then authentication will fail.

Capture Options

To use fast authentication mode, use the same FingerCaptureOptions object used for a normal finger capture. However, to perform fast authentication, initialize it with one of following values:

• FingerCaptureModeAuthentication for the one hand

Set the referenceTemplates property of the FingerCaptureOptions with reference templates and the captureTimeout property to the desired maximum number of seconds (recommended value:10) for the capture.

Optionally, set a custom value in the threshold property with a minimum score value (default and recommended value is 3500) to obtain during the fast authentication process.

Implementing a Fast Authentication Use Case

To perform a fast authentication implement the following steps.

1. Get the reference templates of the end-user you're trying to authenticate stored in BIOStore during enrollment of that end-user with following method:

   Swift
   Objective-C
   1func fingerTemplates(for userUuid: String, completion: @escaping ([BIOTemplate]?) -> Void) {
   2    BIOStore.listTemplates(withUserUUID: userUuid, withModality: BIOModalityFrictionRidge) { (referenceTemplates, _) in
   3        completion(referenceTemplates)
   4    }
   5}

2. With obtained reference templates, create FingerCaptureOptions with a chosen FingerCaptureMode:

   Swift
   Objective-C
   1let options = FingerCaptureOptions(mode: .authentication, hand: .right)
   2options.captureTimeout = 10
   3options.overlay = .ON
   4options.referenceTemplates = templates

3. Use the newly created options to create a FingerCaptureHandler and set its delegate:

   Swift
   Objective-C
   1BIOSDK.createFingerCaptureHandler(with: options) { captureHandler, error in
   2    guard let captureHandler = captureHandler, error == nil else {
   3        // Error, cannot create capture handler.
   4        return
   5    }
   6    // Save a reference to created capture handler.
   7    self.captureHandler = captureHandler
   8
   9    // Set delegate to receive fast authentication result.
   10    self.captureHandler?.delegate = self
   11
   12    // Set the preview used for displaying image from the camera.
   13    self.captureHandler?.preview = self.previewImageView
   14
   15    // Start the capture.
   16    self.captureHandler?.startCapture(completionHandler: { error in
   17        guard error == nil else {
   18            // Error, cannot start the capture.
   19            return
   20        }
   21        // Capture started.
   22    })
   23}

4. Implement the delegate method to receive the fast authentication result:

   Swift
   Objective-C
   1// When fast authentication is finished this callback returns information if it was successful.
   2func fastAuthenticationFinished(_ authenticationResult: BIOAuthenticationResult?, withError error: Error?) {
   3    // Check for any capture error.
   4    guard let authenticationResult = authenticationResult, error == nil else {
   5        // Error, capture failed.
   6        return
   7    }
   8
   9    guard authenticationResult.matchesSuccessfully else {
   10        // Error, fast authentication matching with reference templates failed.
   11        return
   12    }
   13
   14    // User has been authenticated successfully with provided reference templates.
   15    print("Fast authentication score: \(authenticationResult.score)")
   16}

Result

BIOAuthenticationResult

This object represents an authentication result.

Finger Matching 

Finger matching is a process that allows the comparison of fingerprints captured previously, for example during and end-user enrollment process, with other fingerprints perhaps captured during an end-user authentication process. For matching to be successful, the BIOTemplate objects need to have the same biometric modality. With finger templates that's BIOModalityFrictionRidge.

Execution Flow

1. Create the BIOMatcherHandler.

2. Prepare the BIOBiometricCandidate object with candidate templates which usually are created during the authentication process from captured BIOImage objects.

3. Prepare the BIOBiometricReference object with reference templates which usually are previously saved to the database during the enrollment process.

4. Upon successful matching, a BIOAuthenticationResult object is delivered with information.

Implementing Finger Matching

To perform finger matching, implement the steps below.

1. Create the matching handler:

   Swift
   Objective-C
   1BIOSDK.createMatcherHandler(with: BIOMatcherHandlerOptions()) { (handler, error) in
   2    guard let handler = handler, error == nil else {
   3        // Error, cannot create matcher handler.
   4        return
   5    }
   6    // Save a reference to created matcher handler.
   7    self.matcherHandler = handler
   8}

2. Prepare candidate templates for comparison with the reference templates. For the standard authentication process, create the templates those for all of the captured BIOImage objects with a function:

   Swift
   Objective-C
   1func detectBiometrics(for image: BIOImage, completion: @escaping ([BIOTemplate]?) -> Void) {
   2    let options = BIODetectBiometricOptions(location: image.biometricLocation, withModality: BIOModalityFrictionRidge)
   3    self.matcherHandler.detectBiometric(with: options, with: image) { (templates, error) in
   4        completion(templates)
   5    }
   6}

3. Prepare the BIOBiometricCandidate object after all of the candidate templates have been obtained:

   Swift
   Objective-C
   1let candidate = BIOBiometricCandidate()
   2candidate.addTemplates(templates)

4. Prepare the reference templates. For the standard authentication process, get the previously stored templates from the BIOStore with a function such as in the example below:

   Swift
   Objective-C
   1func fingerTemplates(for userUuid: String, completion: @escaping ([BIOTemplate]?) -> Void) {
   2    BIOStore.listTemplates(withUserUUID: userUuid, withModality: BIOModalityFrictionRidge) { (referenceTemplates, _) in
   3        completion(referenceTemplates)
   4    }
   5}

5. Prepare the BIOBiometricReference object when all of the reference templates have been obtained:

   Swift
   Objective-C
   1let reference = BIOBiometricReference(userUUID: userUuid)
   2reference.addTemplates(referenceTemplates)

6. Compare a candidate with the reference to verify if there is a match:

   Swift
   Objective-C
   1let options = BIOAuthenticationOptions(modality: BIOModalityFrictionRidge)
   2self.matcherHandler.authenticate(with: options, with: candidate, with: reference) { (authenticationResult, error) in
   3    guard let authenticationResult = authenticationResult, error == nil else {
   4        // Error, authentication failed.
   5        return
   6    }
   7    guard authenticationResult.matchesSuccessfully else {
   8        // Error, matching with reference templates failed.
   9        return
   10    }
   11
   12    // User has been authenticated succesfully with provided reference templates.
   13    print("Authentication score: \(authenticationResult.score)")
   14}

Parameters

Result

BIOAuthenticationResult

This object represents an authentication result.

Capture Errors 

These are the errors returned after a finger capture attempt fails:

Note 1:

Finger capture may also fail with a BIOCapturingErrorBadCaptureFingers error when the verification mechanism refuses to accept the scanned fingerprints. It can happen when there are no actual fingerprints scanned or the quality of scanned images is too low or the matching threshold value is set too high.

Note 2:

When the liveness check detects fraud, no error is returned. Liveness status can be found under captureInfo.liveness, and is returned with the following callback:

Swift
Objective-C
1func capturedFingers(_ images: [BIOImage]?, withImagesToDisplay imagesToDisplay: [FingerImagePreview]?, with captureInfo: FingerCaptureResult?, withError error: Error?)

Storing Biometrics Data 

BIOStore is responsible for managing the biometrics data on a device's persistent memory. It can be used when there is no other external database that can store such information. It consists of group of static methods that can be used to perform basic database operations on biometric templates and end-users.

Template Storage

Biometric data gathered from each captured finger can be persistently stored as a BIOTemplate object. BIOStore provides methods for saving and managing saved templates, which can be used to:

• Perform basic operations as add, get, update, remove template or remove template associated to any one end-user

• List all templates stored in the database or query templates assigned to a certain end-user with a given UUID

End-user Storage

BIOUser holds information about the ownership of the biometric templates. An end-user's unique UUID is paired with the end-user's owned templates. BIOStore provides methods for saving and managing saved end-users, which can be used to:

• Perform basic operations as add, get, update, remove or list end-users

• Retrieve end-user that is associated with a given template UUID.

Saving Templates

To save templates using BIOStore implement the following steps. This assumes the finger capture is successful and biometric templates were acquired by using BIOMatcherHandler on an array of captured finger images.

1. Create the BIOUser object.

Swift
Objective-C
1let bioUser = BIOUser()
2bioUser.uuid = UUID().uuidString
3bioUser.name = "User Name"

2. Add the end-user to BIOStore.

Swift
Objective-C
1BIOStore.add(bioUser, withCompletionHandler: nil)

3. For each template set the end-user UUID and add it to BIOStore.

Swift
Objective-C
1for template in self.templates {
2    template.uuidUser = uuid
3    BIOStore.add(template) { (uuid, error) in
4        // Handle completion
5    }
6}

This adds the templates with the associated end-user to persistent storage.

New finger capture API 

Introduction 

In order to make integration of the SDK easier and more intuitive - new API for Finger Capture has been delivered. It is based on use cases that are self-explaining which provide specific information depending on a given use case. This allows integrator to focus on working with the data provided by the SDK rather than on SDK configuration.

NOTE: As for now, the new API supports only latent use case.

Integration 

Integration of SDK consists of three steps:

1. Activating license and camera permission.
2. Adding FingerCaptureView to the layout.
3. Setting up capture.

License activation and camera permission

In order to use SDK proper license has to be activated. Getting started section shows how to handle license and permissions.

Adding FingerCaptureView to the layout

It inherits from UIView and has to be used as a preview on the capture's UI. FingerCaptureView is also used to start finger capture and cancel it if needed. So this is not only a capture preview but also entry point to the SDK.

Swift
1class FingerCaptureSDK.FingerCaptureView {
2    func setup(useCase: UseCase, uiSettings: UISettings?)
3    func start()
4    func cancel()
5}

In project that uses storyboards FingerCaptureView (from FingerCaptureSDK module) should be added as an IBOutlet to a layout of the view used for finger capture.

Swift
1@IBOutlet private weak var captureView: FingerCaptureView!

Setting up capture

In order to start capture, it is essential to create a specific use case instance. Each use case ahs a settings property that contains session configuration and set of delegates that will be used to handle callback methods. Use cases and delegates are described in more detail in the next paragraphs - Use Cases, Delegates.

To easily customize the look and feel of finger capture, an optional parameter UISettings can be created additionally. More on that parameter here.

Once these three steps are satisfied, theFingerCaptureView can be set up by passing use case instance and optionally UI settings as parameters. After setting up a captureView, capture can be started by calling start() method. Delegate attached to the use case will receive data from the capture.

Swift
1import FingerCaptureSDK

Swift
1let useCase = // create use case
2    let uiSettings = // optionally create ui settings
3    self.captureView.setup(with useCase: useCase, uiSettings: uiSettings)
4    self.captureView.start()

Capture process can be canceled by calling cancel() method.

Use Cases 

Capture settings of FingerCaptureSDK are done by using proper, predefined configuration, designed for specific use case. In this way capture configuration is more intuitive and less confusing. Below you can find list of available use cases.

LatentUseCase

This use case can be used to capture a fingerprint of secretion of the skin. The fingerprint will be returned in PNG format. To create LatentUseCase, following properties must be provided:

Swift
1let delegates = LatentCaptureDelegates(/** described in Delegates section **/)
2    let useCase = LatentUseCase(settings: LatentCaptureSettings(timeout: 10), delegates: delegates)

LatentCaptureSettings

UISettings

Optional parameter that can contain configuration of UI elements visibility used in finger capture process displayed on FingerCaptureView. All UI elements are enabled by default.

Swift
1let uiSettings = FingerCaptureUISettings(tappingFeedbackSettings: TappingFeedbackUISettings(show: true),
2                                             distanceIndicatorSettings: DistanceIndicatorUISettings(show: true),
3                                             feedbackSettings: FingerFeedbackUISettings(show: true),
4                                             progressBarSettings: ProgressBarUISettings(show: true),
5                                             fingerOverlaySettings: FingerOverlaysUISettings(show: true))

Delegates 

This section describes delegates available for specific use cases within new API for finger capture. Please remember that all UI operations should be performed on main thread.

Capture Delegates

Delegates are used as a mechanism to return information about capture process and status. To receive such information simply set an instance of your class as a delegate and implement methods from the protocol. Delegates are dedicated for specific use cases. However, all use cases have common 3 general delegates, which are as follows:

Finger feedback delegate

Provides information whether the distance between fingers (fingerprints) and the phone is correct. Works only with calibrated devices. This listener is optional and is useful when UISettings are not provided.

Swift
1func captureFeedbackReceived(_ info_: FingerCaptureInfo)

Method called after feedback info is available. Provides FingerCaptureInfo which is an enum with possible messages. Those feedback messages can be mapped and displayed to the user on the UI. For example, tooFar can be mapped to "Move your fingers closer". More examples can be found in FingerSampleApp.

FingerCaptureInfo

Finger capture (distance) feedback for the end-user.

Finger tracking delegate

Provides coordinates of users finger positions on screen. For latent use case it provides rectangle in which the latents should be visible on the preview.

Swift
1func captureInfoReceived(_ trackingInfo: [FingerBox])

Delegate provides a list of FingerBox that has coordinates and dimensions of a frame that can be drawn on the preview image, indicating finger location.

FingerBox

Capture Distance Delegate

Returns information associated with indication of optimal distance range between the phone lens and the fingerprint.

Swift
1func captureDistanceRangeInformationReceived(_ rangeResult: CaptureDistanceRangeResult)

CaptureDistanceRangeResult

This indicates whether the distance of the fingers (fingerprints) distance to the phone camera lens is available and provides optimal distance range for the device.

CaptureDistanceRange

This represents the range of distances between the fingers (fingerprints) and the phone camera lens.

Swift
1func currentCaptureDistanceChanged(to currentCaptureDistance: CurrentCaptureDistance)

CurrentCaptureDistance

This represents current fingers (fingerprints) distance to the phone camera lens.

Latent Capture Delegates

Below delegates are meant only for latent use case.

Swift
1let fingerDelegates = FingerCaptureDelegates(currentDistanceDelegate: self, feedbackDelegate: self, trackingDelegate: self)
2    let delegates = LatentCaptureDelegates(resultDelegate: self, torchDelegate: self, fingerCaptureDelegates: fingerDelegates)

Torch Delegate

Provides TorchController that can be used to control the device torch.

Swift
1func torchControllerProvided(_ torchController: TorchController)

NOTE: After capture finished, the torch is automatically turned off.

TorchController

Torch

Represents device torch status.

Latent Result delegate

Delegate that has one method, which is being called after latent capture is finished.

Swift
1func captureDidFinish(with result: LatentSuccess)

It provides LatentSuccess parameter with latent image. No other callback will occur after this method.

LatentSuccess

LatentImage

Swift
1func captureDidFail(with error: CaptureError)

It provides the CaptureError parameter to inform why the capture failed. No other callback will occur after this method.

Errors 

CaptureError object contains a lot of useful information that helps in handling a failed flow.

ErrorType

ImageUtils 

Objective-C
1- (NSData *)toJPEG;

Objective-C
1- (NSData *)toJPEGWithQuality:(CGFloat)quality;

Objective-C
1+ (UIImage*)imageFromBIOImage:(BIOImage*)bioImage

Objective-C
1+ (BIOImage*)BIOImageFromUIImage:(UIImage*)image;

Objective-C
1- (BIOImage*)BIOImageWithColorSpace:(BIOColorSpace)colorSpace;

Objective-C
1- (NSData*)dataByCompressingImageWithQuality:(uint32_t)quality

Objective-C
1- (BIOImage*)imageByCompressingImageWithQuality:(uint32_t)quality

Objective-C
1- (NSData*)dataByCompressingImageToSizeInKilobytes:(CGFloat)sizeInKilobytes

Objective-C
1- (BIOImage*)imageByCompressingImageToSizeInKilobytes:(CGFloat)sizeInKilobytes

Objective-C
1- (NSData*)dataByCompressingImageToWSQRatio:(CGFloat)ratio withScannerBlack:(Byte)scannerBlack andScannerWhite:(Byte)scannerWhite;

Objective-C
1- (BIOImage*)imageByCompressingImageToWSQRatio:(CGFloat)ratio withScannerBlack:(Byte)scannerBlack andScannerWhite:(Byte)scannerWhite;

Objective-C
1- (NSData*)dataByCompressingImageToJPEG2000InKilobytes:(CGFloat)maximumSizeInKilobytes

Objective-C
1- (BIOImage*)imageByCompressingImageToJPEG2000InKilobytes:(CGFloat)maximumSizeInKilobytes

Objective-C
1+ (BIOImage*)cropImage:(BIOImage*)bioImage toRegion:(BIODocumentTrackingInformation*)documentTrackingInfo;

Objective-C
1- (instancetype _Nullable)cropToRect:(CGRect)rect withMargin:(CGFloat)margin;
2- (instancetype _Nullable)cropToRect:(CGRect)rect; // margin = 0

Objective-C
1- (instancetype _Nullable)cropToRegionWithPoint1:(CGPoint)point1 point2:(CGPoint)point2 point3: (CGPoint)point3 point4:(CGPoint)point4 withMargin:(CGFloat)margin;
2- (instancetype _Nullable)cropToRegionWithPoint1:(CGPoint)point1 point2:(CGPoint)point2 point3: (CGPoint)point3 point4:(CGPoint)point4; // margin = 0

API reference 

BiometricSDK 

Get Info about Biometric Capture SDK

The purpose of this method is allow the integrator to retrieve information about the SDK.

Objective-C
1BIOSDKInfo *info = [BIOSDK getInfo];

Returns

An object of the BIOSDKInfo type with the information about the SDK.

Create a FingerCaptureHandler

This retrieves a capture handler to perform finger biometric capture operations. You must configure first the capture options.

• Please check the use case named Capture finger Biometrics.

• Also, you can check all the features provided by this handler here.

Objective-C
1@interface ViewController () <FingerCaptureHandlerDelegate>
2    @property (strong, nonatomic) id<FingerCaptureHandler> captureHandler;
3    @end
4    ...
5    [BIOSDK createFingerCaptureHandlerWithOptions:[FingerCaptureOptions new] withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error)        {
6      if (!error) {
7        self.captureHandler = captureHandler;
8        self.captureHandler.delegate = self;
9        ...
10      }
11    }];

Note: The errors code list is here

Create a BIOMatcherHandler

This retrieves a handler to perform all the matching, identifying, and template coding operations.

• Please check the use case named Create BIOMatcherHandler.

• Also, you can check all the features provided by this handler here.

Objective-C
1@interface ViewController () <BIOCaptureHandlerDelegate>
2    @property (strong, nonatomic) id<FaceCaptureHandler> captureHandler;
3    @end
4    .....
5    [BIOSDK createMatcherHandlerWithOptions:[BIOMatcherHandlerOptions new]
6                      withCompletionHandler:^(id<BIOMatcherHandler> matcherHandler, NSError* error) {
7        self.matcherHandler = matcherHandler;
8        ....
9    }];

BIOReplayProtocol

This protocol defines the methods that will be available in all capture handlers. However, they should be implemented to reference its sub protocols (eg. FaceCaptureHandlerDelegate) instead of BIOReplayProtocol.

captureFinishedWithError

This method is called whenever a capture finished with an error and cannot be resumed by Biometric Capture SDK.

Objective-C
1-(void)captureFinishedWithError:(NSError*)error

replayDidFinishRecording

This method is called whenever a replay finished playing. These replays are used to play the recorded videos of a capture for debugging purposes.

Objective-C
1-(void)replayDidFinishRecording

Generic SDK Objects

This section is going to cover the generic objects that are necessary to use the Biometric Capture SDK.

BIOSDKInfo

This exposes information about the SDK.

Parameters

BIOBiometrics

This class holds all the different Biometrics that are going into a subclass.

Parameters

BIOImage

This is the image object returned by the SDK. Its subclass is BIOBiometrics.

Parameters

BIOTemplate

This is a Biometric template object returned by the SDK. Its subclass is BIOBiometrics.

Parameters

BIOUser

This is the user object used to represent an individual in the SDK.

Parameters

BIOVideoRecordingOptions

This is the video recording object used to configure video recording.

BIODebugDataSettings

This is an object used for debug purposes. Currently it contains only one parameter which is a file path used for RTV video playback.

Enums

BIOLogLevel

These are the constants used to configure logs.

BIOColorSpace

These are the ColorSpace constants.

BIOLocation

These are the biometric location constants.

BIOModality

These are the biometric modality constants.

BIOCaptureHandlerError

These are errors that can be thrown when there is an error with the capture handler.

BIOCapturingError

These are errors that can be thrown when there is an error during or after the capture.

BIOCamera

These are the constants used to configure the behavior of BioCapture.

BIOOverlay

This is the enum used to configure the behavior of BioCapture.

BIOPreviewColorspace

These are the flags used to set the color space for the preview of the camera.

FingerCaptureHandler 

Delegate

This sets the listener to receive the biometric information.

Objective-C
1handler.delegate = ... //Object that implements `FingerCaptureHandlerDelegate` protocol

Preview

This sets the camera preview.

Objective-C
1handler.preview = ... //An `UIImageView`

Note: To stop the camera preview, set the preview to nil.

Debug Settings

This sets the camera preview.

Objective-C
1BIODebugDataSettings *settings = [[BIODebugDataSettings alloc] init];
2      settings.rtvFilePath = ... //A path to RTV video file used for video playback.
3      handler.debugSettings = settings;

Start Capture

This starts the biometric capture.

Objective-C
1[handler startCaptureWithCompletionHandler:^(NSError \* error) {
2              ...
3          }];

Stop Capture

Objective-C
1[handler stopCaptureWithCompletionHandler:^(NSError \* error) {
2              ...
3          }];

Switch Camera

This switches between different cameras.

Objective-C
1[handler switchCamera:BIOCameraFront withError:&error];
2          [handler switchCamera:BIOCameraRear withError:&error];

Overlay

This sets the overlay option.

Objective-C
1[self setOverlay:BIOOverlayOFF withError:&error];
2        [self setOverlay:BIOOverlayON withError:&error];

Options

This retrieves the capture options used in this handler.

Note: Readonly

Objective-C
1FingerCaptureOptions* options = handler.options;

Partial Dump Video

This dumps the last played sequences.

Objective-C
1[handler requestPartialDumpVideoWithError:&error];

Note: To dump a partial video, capture it with the partial dump video recording set to enabled. This should have been done previously.

Full capture time (Deprecated)

Now this method returns the same value as the captureTimeout in the FingerCaptureOption.

Objective-C
1NSTimeInterval fullCaptureTime = handler.fullCaptureTime;

Capture distance range

This allows to check if the device is calibrated for optimal distance feedback feature. If yes, it provides the distance ranges, which can be used to present graphical indicator for the end user.

Objective-C
1FingerCaptureDistanceRangeResult *rangeResult = handler.captureDistanceRange;
2        if (rangeResult.range != nil) {
3            rangeResult.range.rangeMin // 0.0
4            rangeResult.range.optimalMin
5            rangeResult.range.optimalMax
6            rangeResult.range.rangeMax // 1.0
7        } else {
8            // optimal distance feedback feature is not available.
9            // rangeResult.unavailabilityReason can be used to check reason.
10        }

Destroy

This releases all the handler resources.

Objective-C
1[handler destroy];

FingerCaptureHandlerDelegate 

FingerCaptureHandlerDelegate is a sub protocol of BIOReplayProtocol and implements all of its methods as well.

fingerCaptureReceivedTrackingInfo:withError:

This method is called when there is new tracking information with the coordinates of the finger position.

Objective-C
1-(void)fingerCaptureReceivedTrackingInfo:(NSArray<FingerTrackingInfo*>* )trackingInfo
2                                   withError:(NSError*)error

capturedFingers:withImagesToDisplay:withResult:withError:

This method is called when there are fingers captured.

Objective-C
1- (void)capturedFingers:(NSArray<BIOImage *> * _Nullable)matchingImages
2    withImagesToDisplay:(NSArray<FingerImagePreview *> * _Nullable)imagesToDisplay
3             withResult:(FingerCaptureResult * _Nullable)captureInfo
4              withError:(NSError * _Nullable)error;

(DEPRECATED) capturedFingers:withResult:withError:

Note: This method is deprecated, use capturedFingers:withImagesToDisplay:withResult:withError: instead.

This method is called when there are fingers captured.

Objective-C
1- (void)capturedFingers:(NSArray<BIOImage*>*)images
2      withResult:(FingerCaptureResult*)result
3              withError:(NSError*)error

capturedHand:withError:

This method is called when there is a hand captured.

Objective-C
1-(void)capturedHand:(BIOImage*)image
2                withError:(NSError*)error

fastAuthenticationFinished:withError:

This method is called when fast authentication was selected. This returns the result of the authentication.

Objective-C
1-(void)fastAuthenticationFinished:(BIOAuthenticationResult*)authenticationResult
2                            withError:(NSError*)error

fingerCaptureReceivedCurrentDistance:

This method is called when current distance between the fingers and the phone camera lens changed. It provides distance value (e.g in order to create your own optimal distance indicator on UI).

Objective-C
1- (void)fingerCaptureReceivedCurrentDistance:(FingerCaptureCurrentDistance *)distance

fingerCaptureReceivedFeedback:

This method is called when there is information/feedback to the user available. It mostly provides feedback for the end-user whether the distance is optimal.

Objective-C
1- (void)fingerCaptureReceivedFeedback:(FingerCaptureInfo)info

Helper Objects 

FingerCaptureOptions

This object is used to configure the behavior of FingerCaptureHandler.

BIOLivenessResult

This object is used to check the liveness check result. Note: Liveness check is disabled by default. To enable it, use the livenessType property in the FingerCaptureOptions object.

FingerCaptureResult

This object aggregates the liveness results and matching score.

FingerImagePreview

This object provides fingerprint images for display purposes.

FingerTrackingInfo

This is the finger tracking object returned by the SDK.

Parameters

FingerCaptureDistanceRangeResult

This tells if the fingers distance to the phone camera lens is available and provides optimal distance range for the device.

FingerCaptureDistanceRange

This represents fingers distance range to the phone camera lens.

FingerCaptureCurrentDistance

This represents current fingers distance to the phone camera lens.

Enums 

FingerCaptureMode

This enum is used to configure the behavior of BioCapture.

FingerCaptureLivenessType

This enum is used to enable liveness check.

BIOLivenessResultStatus

These are the liveness result constants.

BIOHand

Specifies which hand is being scanned.