IDV iOS Fingers library

v9.5.0

Introduction

IDV iOS Fingers provides components for contactless finger capture and related functionalities which are easy to integrate into an iOS application.

Requirements

Xcode 26.2+
iOS 15.1+
Swift or Objective-C
CocoaPods or Swift Package Manager

In the major release 9.0.0, Objective-C support is deprecated, and in the following major release 10.0.0 it will be removed. If your iOS application integrates IDV iOS Fingers using Objective-C, you will need to implement the bridging on your side.

Distribution

Modularization

IDV iOS Fingers is divided into core module and optional feature modules. This enables you to reduce the size of the library and include only modules that are actually used in your use case.

IDV iOS Fingers is divided into following modules:

dot-fingers-core (Required) - provides API for all the features and functionalities.
dot-fingers-detection (Optional) - enables the finger detection feature.
dot-fingers-transformation (Optional) - enables the finger-to-fingerprint transformation feature.

Each feature module can have other modules as their dependency and cannot be used without it, see the table below.

Table 1. Module dependencies
Module	Dependency
`dot-fingers-detection`	`dot-fingers-core`
`dot-fingers-transformation`	`dot-fingers-core`

Swift Package Manager

IDV iOS Fingers can be easily integrated into Xcode project in: Project → Package Dependencies.

Use https://github.com/innovatrics/dot-ios-sdk-spm.git repository and choose version you want to use. There you can select set of DotFingers* packages you want to use. All the required dependencies will be downloaded with the selected package set.

Cocoapods

In order to integrate IDV iOS Fingers into your project, the first step is to insert the following line of code on top of your Podfile.

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

Then, add the module(s) which you want to use to your Podfile. All the required dependencies will be downloaded with the selected module(s).

Podfile

source 'https://github.com/innovatrics/innovatrics-podspecs'

use_frameworks!

target 'YOUR_TARGET' do

pod 'dot-fingers-detection'
pod 'dot-fingers-transformation'

end

In case of CocoaPods problem with pod install, try to clone the private pod repository manually.

pod repo remove innovatrics
pod repo add innovatrics https://github.com/innovatrics/innovatrics-podspecs

Supported Architectures

IDV iOS Fingers provides all supported architectures in the distributed XCFramework package. Device binary contains: arm64. Simulator binary contains: arm64.

Debug symbols

Due to security concerns, IDV iOS Fingers does not include debug symbol files (dSYM files) in the distributed XCFramework package. As a result, Xcode will generate warnings when uploading an iOS application that includes IDV iOS Fingers to the App Store. These warnings can be safely ignored.

Licensing

In order to use DotSdk in your iOS application, it must be licensed. The license can be compiled into the application as it is bound to Bundle Identifier specified in the General tab in Xcode.

The Bundle ID can be also retrieved in runtime by calling DotSdk.shared.bundleId.

In order to obtain the license, please contact your Innovatrics’ representative specifying Bundle ID. After you have obtained your license file, add it to your Xcode project and use it during the DotSdk initialization, as shown below.

Permissions

Set the following permission in Info.plist:

Info.plist

<key>NSCameraUsageDescription</key>
	<string>Your usage description</string>

Basic Setup

Initialization

Before using any of the components, you need to initialize IDV SDK with the license, DotFingersLibraryConfiguration object and modules configurations you want to use. Each module can be accessed by its *ModuleConfiguration class. IDV iOS Fingers is distributed as a set of XCFramework packages. Each module is distributed as a single XCFramework package, see the table below.

You do not need to import the modules you want to use, but you have to have them as a dependencies in your project.

Table 2. XCFramework packages
Module	Configuration Class	XCFramework
`dot-fingers-detection`	DotFingersDetectionModuleConfiguration	DotFingersDetection.xcframework
`dot-fingers-transformation`	DotFingersTransformationModuleConfiguration	DotFingersTransformation.xcframework

IDV SDK Sample shows how to initialize IDV SDK with DotFingersLibraryConfiguration. DotSdk.shared.initialize() method should be called on background thread.

After you have successfully finished initialization, you can use all added features by importing only DotFingersCore Swift module in your source files. Keep in mind that if you try to use any feature which was not added during initialization IDV SDK will generate fatal error.

Deinitialization

When you have finished using the IDV iOS Fingers, it is usually a good practice to deinitialize it in order to free the memory. You can deinitialize IDV iOS Fingers only after the complete process is finished and not within the life cycle of individual components. This can be performed using the DotSdk.shared.deinitialize() method. If you want to use the IDV iOS Fingers components again, you need to call DotSdk.shared.initialize() again.

Logging

IDV iOS Fingers supports logging using a global Logger class. You can set the log level as follows:

import DotFingersCore

Logger.logLevel = .debug

Log levels:

debug
info
warning
error
none

Each log message contains DotFingers tag. Keep in mind that logging should be used just for debugging purposes.

Components

Overview

IDV iOS Fingers provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the IDV iOS Fingers functionality. UI components are built on top of non-UI components. Components having UI are available as UIViewController classes and can be embedded into the application’s existing UI or presented using the standard methods.

List of Non-UI Components

FINGER DETECTOR: A component for performing finger detection on an image.
FINGER TO FINGERPRINT TRANSFORMER: A component for transforming captured finger images into fingerprint images.
FINGERS AUTO CAPTURE CONTROLLER: A component for capturing good quality images of the four human fingers.

List of UI Components

UI FINGERS AUTO CAPTURE: A visual component for capturing good quality images of the four human fingers.

Non-UI Components

Finger Detector

The FingerDetector class provides a finger detection functionality. This component requires dot-fingers-detection module.

Create a FingerDetector:

let fingerDetector = FingerDetector()

To perform detection, call the following method on the background thread:

let fingers = try fingerDetector.detect(image: image, limit: 4)

Finger To Fingerprint Transformer

The FingerToFingerprintTransformer class transforms captured contactless finger images into fingerprint images. This component requires dot-fingers-transformation module.

Create a FingerToFingerprintTransformer:

let transformer = FingerToFingerprintTransformer()

To transform a single finger image into a fingerprint image, call the following method on the background thread:

let fingerprintImage = try transformer.transform(fingerBundle: fingerBundle)

To transform all four finger images at once, pass FingerBundles and receive FingerprintImages:

let fingerprintImages = try transformer.transform(fingerBundles: fingerBundles)

Fingers Auto Capture Controller

The FingersAutoCaptureController class provides a stateful fingers auto capture functionality. This component requires dot-fingers-detection module.

You can configure FingersAutoCaptureController using FingersAutoCaptureController.Configuration.

Create FingersAutoCaptureController:

let configuration = try FingersAutoCaptureController.Configuration(
    autoCapture: .init(
        minValidSamplesInRowToStartCandidateSelection: 2,
        candidateSelectionDurationMillis: 2000
    ),
    validators: validators,
    detectionArea: detectionArea)
let controller = FingersAutoCaptureController(configuration: configuration)

You can use detectionArea to specify the region in the input image which will be used for finger detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

let detectionArea = RectangleDouble(left: 0, top: 0.3, right: 1.0, bottom: 0.7)

If detectionArea is set to nil(default) the full input image is used for finger detection.

To capture a good quality finger images, call the process() method and captured() method, see the sample:

let processingResult = try fingersAutoCaptureController.process(sample: sample)
try fingersAutoCaptureController.captured(sample: photoSample)

The controller evaluates the finger image requirements for each sample (frame). Once the controller detects enough (minValidSamplesInRowToStartCandidateSelection) valid samples in a row for some finger, it emits captureDepth event and then waits for the photo capture with depth. Captured photo with depth is evaluated and once the controller has valid photo with depth for each finger, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best finger image candidates are returned and the fingers auto capture process is over.

UI Components

Camera handling

Camera lifecycle

IDV iOS Fingers view controller will start the camera in viewWillAppear(:) lifecycle method. IDV iOS Fingers view controller will stop the camera in viewDidDisappear(:) lifecycle method.

Camera permission

IDV iOS Fingers view controller will check the camera permission right before the camera is started. If the camera permission is granted the view controller will start the camera. If the camera permission is denied the view controller will call *ViewControllerNoCameraPermission(:) callback. Implement this callback in order to navigate the user further in your app workflow. If the camera permission is not determined the view controller will use iOS API - AVCaptureDevice.requestAccess(for: .video) method to request the camera permission. This method will present the system dialog to the user of the app. The user of the app can grant or deny the camera permission and then the view controller will proceed the same way as it does during the camera permission check as was explained at the beginning of this section.

View Controller Configuration

Components containing UI are embedded into the application as view controllers. All view controllers can be embedded into your own view controller or presented directly. Each view controller can be configured using its *Configuration class and each view controller can have its appearance customized using its *Style class.

To present view controller:

let viewController = FingersAutoCaptureViewController(configuration: .init(), style: .init())
viewController.delegate = self
navigationController?.pushViewController(viewController, animated: true)

To embed view controller into your view controller:

override func viewDidLoad() {
    super.viewDidLoad()

    addChild(viewController)
    view.addSubview(viewController.view)
    viewController.view.translatesAutoresizingMaskIntoConstraints = false
    viewController.didMove(toParent: self)

    NSLayoutConstraint.activate([
        viewController.view.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor),
        viewController.view.leadingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.leadingAnchor),
        viewController.view.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor),
        viewController.view.trailingAnchor.constraint(equalTo: view.safeAreaLayoutGuide.trailingAnchor)
    ])
}

Safe Area

IDV iOS Fingers view controllers ignore safe area layout guide when they layout their subviews. Therefore, for example if you push IDV iOS Fingers view controller using UINavigationController, you will get incorrect layout. If you want to respect safe area layout guide, you should embed IDV iOS Fingers view controller in a container view controller and setup the layout constraints accordingly.

Video Recording for Identity Proofing

UI components support video recording. You can enable this feature in the component’s configuration using the isVideoCaptureEnabled parameter. The duration of the captured video is limited to a maximum of 8 seconds, corresponding to the end of the processing session. The captured video is bundled into the component’s result binary content and can be retrieved via the Digital Identity Service (DIS) for the purposes of Identity proofing.

UI Fingers Auto Capture

The view controller with fingers placeholder which is used for capturing finger images. This component requires dot-fingers-detection module.

You can configure FingersAutoCaptureViewController using FingersAutoCaptureViewController.Configuration. You can customize the appearance of FingersAutoCaptureViewController using FingersAutoCaptureViewController.Style. You can handle the FingersAutoCaptureViewController events using its delegate FingersAutoCaptureViewControllerDelegate.

Start the Fingers Auto Capture process:

Check whether IDV iOS Fingers is initialized.
If IDV iOS Fingers is initialized, you can call the start() method immediately. If not, you need to initialize IDV iOS Fingers and call start().

When the fingers auto capture process finishes successfully, the result will be returned via the fingersAutoCaptureViewController(:finished:) callback.

In case you want to force the capture event, call the requestCapture() method. The most recent image will be returned via the fingersAutoCaptureViewController(:finished:) callback asynchronously.

Call start() method again in case you need to start over the fingers auto capture process. You can also call start() method to stop and start over ongoing process as well.

In case you want to stop the fingers auto capture process prematurely, call the stop() method.

Once the fingers auto capture process has started, it is not safe to deinitialize the IDV iOS Fingers until either you have manually called the stop() method, or the following callback is called:

fingersAutoCaptureViewController(:finished:)

Quality Attributes of the Output Image

You may adjust quality requirements for the output image. To perform this, you can use the pre-defined builder FingersAutoCaptureQualityAttributeThresholds.Presets.standard with recommended thresholds and pass it to BaseFingersAutoCaptureViewController.Configuration by setting the qualityAttributeThresholds. You can also create your own instance of FingersAutoCaptureQualityAttributeThresholds from scratch or based on pre-defined builders according to your needs.

Possible ways how to create FingersAutoCaptureQualityAttributeThresholds:

// The standard preset
let standard = FingersAutoCaptureQualityAttributeThresholds.Presets.standard.build()

// Modified thresholds based on the standard preset
let modified = try FingersAutoCaptureQualityAttributeThresholds.Presets.standard
        .minConfidence(minConfidence)
        .build()

// Custom thresholds
let custom = try FingersAutoCaptureQualityAttributeThresholds.Builder()
        .minConfidence(minConfidence)
        .build()

Available presets (pre-defined builders with thresholds) in FingersAutoCaptureQualityAttributeThresholds.Presets:

standard - The resulting image suitable for evaluation on Digital Identity Service.

Customization of UI Components

Localization

String resources can be overridden in your application and alternative strings for supported languages can be provided following these two steps:

Add your own Localizable.strings file to your project using standard iOS localization mechanism. To change a specific text override corresponding key in this Localizable.strings file.
Set the localization bundle to the bundle of your application (preferably during the application launch in your AppDelegate).

Use this setup if you want to use standard iOS localization mechanism, which means your iOS application uses system defined locale.

import DotFingersCore

Localization.bundle = .main

Custom Localization

You can override standard iOS localization mechanism by providing your own translation dictionary and setting the Localization.useLocalizationDictionary flag to true. Use this setup if you do not want to use standard iOS localization mechanism, which means your iOS application ignores system defined locale and uses its own custom locale.

import DotFingersCore

guard let localizableUrl = Bundle.main.url(forResource: "Localizable", withExtension: "strings", subdirectory: nil, localization: "de"),
      let dictionary = NSDictionary(contentsOf: localizableUrl) as? [String: String]
else { return }

Localization.useLocalizationDictionary = true
Localization.localizationDictionary = dictionary

Localizable.strings

"dot_fingers.fingers_auto_capture.instruction.fingers_not_detected" = "Position your fingers into the placeholder";
"dot_fingers.fingers_auto_capture.instruction.sharpness_too_low" = "More light needed";
"dot_fingers.fingers_auto_capture.instruction.fingers_out_of_bounds" = "Center fingers";
"dot_fingers.fingers_auto_capture.instruction.size_too_small" = "Move closer";
"dot_fingers.fingers_auto_capture.instruction.size_too_large" = "Move back";
"dot_fingers.fingers_auto_capture.instruction.finger_count_too_low" = "Show more fingers";
"dot_fingers.fingers_auto_capture.instruction.finger_count_not_four" = "Show four fingers";
"dot_fingers.fingers_auto_capture.instruction.candidate_selection" = "Stay still…";

Common Classes

`ImageSize`

Class which represents a size of an image. To create an instance:

let imageSize = ImageSize(width: 100, height: 100)

`Image`

Class which represents an image.

To create an instance from CGImage:

let bgraRawImage = ImageFactory.createBgraRawImage(cgImage: cgImage)

To create an instance from CIImage:

let bgraRawImage = ImageFactory.createBgraRawImage(ciImage: ciImage, ciContext: ciContext)

To create CGImage from Image:

let cgImage = CGImageFactory.create(image: image)

To create CIImage from Image:

let ciImage = CIImageFactory.create(image: image)

`DetectionPosition`

Class which represents the position of a detected finger. To create an instance:

let detectionPosition = DetectionPosition(jointTop: jointTop, tip: tip, jointBottom: jointBottom)

Security guidelines

The effectiveness of our video injection prevention feature can be strengthened if the application that implements it includes security recommendations from Apple: App integrity. Which ensure its authenticity that it was downloaded only from the App Store and the transmission of its sensitive data cannot be modified.

OWASP Mobile Application Security

We also strongly recommend following the OWASP Mobile Application Security guidelines. The OWASP Mobile Application Security (MAS) flagship project provides a security standard for mobile apps (OWASP MASVS) and a comprehensive testing guide (OWASP MASTG) that covers the processes, techniques, and tools used during a mobile app security test, as well as an exhaustive set of test cases that enables testers to deliver consistent and complete results.

First release

IDV iOS Fingers library

v9.5.0#

v9.5.0