Extensions 

The BiometricSDK UI Extensions framework is targeted to developers who want to use our default UI with the BiometricSDK framework within their mobile apps. This section covers the BiometricSDKRemote, getting started with AAMVA, and UI extensions for iOS.

iOS BiometricSDKRemote 

Note: ⚠️ BiometricSDKRemote is deprecated.

The BiometricSDKRemote framework is targeted to developers who want to use BIOServer with online liveness and online matching together with BiometricSDK framework within their mobile apps.

Prerequisites

Skills required

The integration tasks require developers with knowledge of:

• Xcode
• Objective-C or Swift
• iOS (minimum version is 15.0)

Resources required

Integration should be performed on a Mac. The tools required are:

• Xcode that support iOS 15
• iOS device

Getting started

Adding the framework to your project

CocoaPods (from Artifactory)

1. To use CocoaPods with Artifactory you must install the cocoapods-art plugin. To install cocoapods-art, run the following command:

Language not specified
1gem install cocoapods-art

2. The plugin uses authentication as specified in a standard .netrc file.

Language not specified
1machine mi-artifactory.otlabs.fr
2login <USERNAME>
3password <PASSWORD>

3. Once set, add our repository to your cocoapod dependency management system:

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

4. At the top of your Podfile add:

Language not specified
1plugin 'cocoapods-art', :sources => [
2    'master',                 # so it could resolve dependencies from master repo (the main one)
3    'smartsdk'                # so it could resolve BiometricSDKRemote depdendency
4]

5. Add the pod in your Podfile:

Language not specified
1pod 'BiometricSDKRemote'

6. Then you can use install as usual:

Language not specified
1pod install

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

Language not specified
1pod repo-art update smartsdk

Manual

1. In the project editor, select the target to which you want to add BiometricSDKRemote.framework.

2. Click the General tab at the top of the project editor.

3. Scroll down to the Embedded Binaries section.

4. Click Add (+).

5. Click Add Other below the list.

6. Find the BiometricSDKRemote.framework file and click Open.

BiometricSDKRemote (deprecated)

BiometricSDKRemote allows you to perform online liveness verification and online matching.

Online liveness verification

The process of liveness verification on the server requires to provide a server url and an individual api key. After that liveness session can be prepared on the server and it returns the challenge parameters as well as the session id. When the user finishes the challenge, it can be verified on the server.

First, prepare the liveness session and get the remote face capture options. Using capture options generated from the server parameters, a capture handler can be created. Successfully created capture handler will contain two parameters: encrypted device id and encrypted master secret. Those two parameters have to be used to obtain device id signature. With valid device id signature, capture session can be started.

The example below show the proper order for preparing the liveness session on the server, getting the parameters followed by creating a face capture handler, obtaining device id signature and using it to start a capture.

Swift
Objective-C
1var remote: BIORBiometricSDKRemote?
2var parameters: BIORLivenessParameters?
3var sessionId: String?
4
5func prepareRemoteFaceCapture() {
6    let options = RemoteFaceCaptureOptions(livenessMode: .passive)
7    remote = BIORBiometricSDKRemote(baseUrl: URL(string: "https://properserver.com")!, apiKey: "properApiKey")
8    guard let parameters = try? BIORLivenessParameters(remoteFaceCaptureOptions: options) else {
9        // handle error, for example show some information to the user
10        return
11    }
12    remote?.prepareLiveness(with: parameters, completionHandler: { (sessionId, livenessParameters, error) in
13        guard error != nil, let livenessParameters = livenessParameters, let sessionId = sessionId else {
14            // handle error, for example show some information to the user
15            return
16        }
17        guard let options = try? livenessParameters.remoteFaceCaptureOptions() else {
18            // handle error, for example show some information to the user
19            return
20        }
21        self.parameters = livenessParameters
22        self.sessionId = sessionId
23        BIOSDK.createRemoteFaceCaptureHandler(with: options) { (captureHandler, error) in
24            self.captureHandler = captureHandler
25            self.captureHandler?.delegate = self
26            self.captureHandler?.preview = self.captureView.previewView
27            self.remote?.obtainSignature(forDeviceId: captureHandler.deviceId, withMasterSecret: captureHandler.masterSecretKey, completionHandler: { [weak self] deviceIdSignature, error in
28                guard let self = self else {
29                    return
30                }
31                guard error == nil, let deviceIdSignature = deviceIdSignature else {
32                    //... Handle error on obtaining device id signature
33                    return
34                }
35
36                self.captureHandler?.startCapture(withDeviceIdSignature: deviceIdSignature)
37            })
38        }
39    })
40}

After performing the challenge on your mobile device (when you receive a BIOFaceImage in the SDK delegate method), you need to send the received encrypted metadata, together with previously saved challenge parameters, to the server, to perform online liveness verification. Then you can verify the status of the challenge on the server. The example below shows how it can be done.

Swift
Objective-C
1func captureFinished(withEncryptedMetadata metadata: BIOEncryptedData) {
2    // ...
3    guard let remote = remoteHandler, let serverRandom = remoteParameters?.serverRandom, let certificates = remoteParameters?.certificates, let sessionId = remoteSessionId else {
4        // handle error, for example show some information to the user
5        return
6    }
7
8    remote?.processLiveness(withMetaData: metadata, serverRandom: serverRandom, certificates: certificates, sessionId: sessionId, { [weak self] error in
9        guard let self = self else {
10            return
11        }
12
13        guard error == nil else {
14            // handle error, for example show some information to the user
15            return
16        }
17        remote.getLivenessStatus(withSessionId: sessionId, { [weak self] image, error in
18            guard let self = self else {
19                 return
20            }
21
22            guard image != nil, error == nil else {
23                // server liveness verification failed
24                return
25            }
26            // verified successfully
27        })
28    })
29}

Online matching

The process of online matching two face images on the server returns a score and can be performed as seen by the example:

Swift
Objective-C
1remote = BIORBiometricSDKRemote(baseUrl: URL(string: "https://properserver.com")!, apiKey: "properApiKey")
2remote?.matchFaces(withReferenceImage: referenceImage, candidateImage: candidateImage, completionHandler: { (score, error) in
3    guard error == nil else {
4        // matching failed
5        return
6    }
7    // check score
8})

As with online liveness verification, for online matching a server URL and server API key must be provided and then just a single method with two image parameters must be called.

Getting started with AAMVA 

The AAMVADecoder framework is targeted to developers who need to decode AAMVA within their mobile apps.

Prerequisites

Skills required

The integration tasks require developers with knowledge of:

• Xcode
• Objective-C/Swift
• iOS (min version is 15.0)

Resources required

Integration should be performed on a Mac. The tools required are:

• Xcode that support iOS 15
• iOS device
• CocoaPods (optional)

Adding the framework to your project

CocoaPods (from Artifactory)

1. To use CocoaPods with Artifactory, you must install the cocoapods-art plugin. To install cocoapods-art, run the following command:

Objective-C
1gem install cocoapods-art

2. The plugin uses authentication as specified in the standard .netrc file.

Objective-C
1machine mi-artifactory.otlabs.fr
2login <USERNAME>
3password <PASSWORD>

3. Add our repository to your CocoaPod dependency management system:

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

4. At the top of your Podfile add:

Objective-C
1plugin 'cocoapods-art', :sources => [
2    'master',                 # so it could resolve dependencies from master repo (the main one)
3    'smartsdk'                # so it could resolve AAMVADecoder depdendency
4]

5. Add the pod in your Podfile.

Objective-C
1pod 'AAMVADecoder'

6. Now you can use install:

Objective-C
1pod install

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

Objective-C
1pod repo-art update smartsdk

Manual

1. In the project editor, select the target to which you want to add the AAMVADecoder framework.
2. Click the General tab at the top of the project editor.
3. Scroll down to the Embedded Binaries section.
4. Click Add (+).
5. Click Add Other below the list.
6. Find AAMVADecoder.framework file and click Open.

Start using the AAMVADecoder

1. Import the framework header to your view controller.

Objective-C
Swift
1#import <AAMVADecoder/AAMVADecoder.h>

2. Initialize the AAMVADecoder with a string scanned from a barcode.

Objective-C
Swift
1NSString *AAMVAString = @"@\nANSI999999070001DL00310265DLDAQ291965255\n"
2                        @"DCSSAMPLE\nDDEU\nDACJOE\nDDFU\nDADNONE\nDDGU\nDCAC\n"
3                        @"DCBNONE\nDCDNONE\nDBD07242018\nDBB02031980\nDBA07242022\n"
4                        @"DBC1\nDAU073 IN\nDAYGRN\nDAG123 MAIN STREET\nDAIANYTOWN\n"
5                        @"DAJST\nDAK240660295\nDCF2048387841483\nDCGUSA\n"
6                        @"DCKPSS to Populate/Replace\nDDAF\nDDB07252013\nDAW175\nDDK1";
7AAMVADecoder *decoder = [[AAMVADecoder alloc] initWithAAMVAString:AAMVAString];

3. Now you can extract information from the initialized decoder with the AAMVADecoder methods.

AAMVADecoder initialization

AAMVADecoder must be initialized with the AAMVAString. After initialization, various information can be extracted from the decoder.

Objective-C
1NSString *AAMVAString = [...]
2AAMVADecoder *decoder = [[AAMVADecoder alloc] initWithAAMVAString:AAMVAString];

Common information

First name:

Objective-C
1- (nonnull NSString*)firstName

Last name:

Objective-C
1- (nonnull NSString*)lastName

Middle name

Objective-C
1- (nullable NSString*)middleName

Sex (M, F, or U)

Objective-C
1- (nonnull NSString*)sex

Country

Objective-C
1- (nullable NSString*)country

Postal code. This may return a short or extended postal code.

Objective-C
1- (nonnull NSString*)postalCode

Postal code short. This returns the short postal code.

Objective-C
1- (nonnull NSString*)postalCodeShort

State (2-digit code). Use issuer property to determine issuing state.

Objective-C
1- (nonnull NSString*)state

City

Objective-C
1- (nonnull NSString*)city

Address line 1. Main Address (for example, 123 MAIN STREET)

Objective-C
1- (nonnull NSString*)addressLine1

Address line 2. Secondary Address (such as APT 101), if applicable

Objective-C
1- (nullable NSString*)addressLine2

Full address. Formatted full address (for example, 123 MAIN STREET, APT 1, SOMECITY, ST 55555)

Objective-C
1- (nonnull  NSString*)fullAddressWithOptions:(AAMVAAddressOptions)options

ID Number. This number is also the driver's license number, if applicable.

Objective-C
1- (nonnull NSString*)idNumber

Characteristics

Race

Objective-C
1- (nullable NSString*)race

Eye color

Objective-C
1- (nonnull NSString*)eyeColorWithFormat:(AAMVAColorFormat)format

Hair color

Objective-C
1- (nullable NSString*)hairColorWithFormat:(AAMVAColorFormat)format

Weight

Objective-C
1-(NSInteger)weightWithFormat:(AAMVAUnitFormat)format

Height

Objective-C
1- (NSInteger)heightWithFormat:(AAMVAUnitFormat)format

Height in feet and inches representation

Objective-C
1- (AAMVAImperialHeight)heightImperialRepresentation

Date of birth

Objective-C
1- (nonnull AAMVAModel_Date*)dateOfBirth

Date of birth as string

Objective-C
1- (nonnull NSString*)dateOfBirthString
2```                                      |
3
4*Issuance date*
5
6```objective-c
7- (nonnull AAMVAModel_Date*)issueDate

Issuance date as string

Objective-C
1- (nonnull NSString*)issueDateString
2```                                     |
3
4*Expiration date*
5
6```objective-c
7- (nonnull AAMVAModel_Date*)expirationDate

Expiration date as string

Objective-C
1- (nonnull NSString*)expirationDateString
2```                                     |
3
4*Find field. Lookup a specific field with a given name.*
5
6```objective-c
7    - (nullable AAMVAModel_DataElement*)findField:(nullable NSString*)field

Meta information

Issuer. Usually the same state as residence (2-letters, for example: CA, AZ)

Objective-C
1- (nullable NSString*)issuer

Country for encoding (for example, USA)

Objective-C
1- (nullable NSString*)encodedCountry

Version (encoded version)

Objective-C
1- (nullable NSString*)version

Document type (for example, DL, ID, BOTH)

Objective-C
1- (nonnull NSString*)documentType

Data sources (list of detected field identifiers)

Objective-C
1- (nullable NSString*)dataSources

status information

Class type. Document class type (for example: C, M)

Objective-C
1- (nonnull NSString*)documentClassType

Driving restrictions (for example, glasses)

Objective-C
1- (nonnull NSString*)documentClassType

Document discriminator

Objective-C
1- (nonnull NSString*)documentDiscriminator

Endorsements

Objective-C
1- (nullable NSString*)endorsements

Compliance type

Objective-C
1- (nullable NSString*)complianceType

Organ donor status

Objective-C
1- (BOOL)donor

Veteran status

Objective-C
1- (BOOL)veteran

Enums

AAMVAColorFormat. Color format (for eyes and hair color methods)

AAMVAUnitFormat. Unit format (for weight and height methods)

AAMVAAddressOptions. Address format options

UIExtensions 

The BiometricSDK UIExtensions API is offered to developers who wish to use our default user interface for BiometricSDK framework within their mobile apps. It simplifies the implementation of features from our SDK by providing easy to use default UI and components that make it easier to create your own user interface for BiometricSDK challenges. In UIExtensions we provide default user interfaces for passive liveness, passive video and join the points challenges that provides the capability to check whether a real person is in front of the camera. Moreover UIExtensions includes a component that assists in obtaining high-quality fingerprint scans and enables the detection of whether the given fingers are genuine.

Pre-requisites

Skills required

The integration tasks shall be done by developers with knowledge of:

• Xcode 14.2
• Swift 5
• iOS (min version is 15.0)

Resources required

Integration should be performed on a Mac.

The tools required are:

• Xcode that support iOS 15 or later
• iOS device

External dependencies

UIExtensions are split into a few different components. Some of them might require an external dependency used for displaying vector animations. We use open source library named Lottie (https://github.com/airbnb/lottie-ios) for vector animations displayed in our default user interfaces. We recommend using cocoapods dependency manager (https://cocoapods.org/) to add this library to your project by adding pod 'lottie-ios', '~> 3.1' in your Podfile when you use components that require it.

Components

The BiometricSDK UIExtensions consist of few components that allow the use our the default user interface with BiometricSDK framework or simplify creating custom user interfaces for the BiometricSDK challenges. There are three main components that allow the execution of various face liveness challenges:

• BiometricSDKUIFaceModePassive,
• BiometricSDKUIFaceModePassiveVideo,
• BiometricSDKUIFaceModeHigh.

All these components provide the capability to check if a real person is in front of the camera. They can all successfully detect frauds, such as taking a picture of another picture with a face of another person.

There is also component for finger variant of BiometricSDK framework which is able to scan fingerprint images acquisition:

• BiometricSDKUIFinger.

BiometricSDKUIFaceModePassive

BiometricSDKUIFaceModePassive is a group of subcomponents used for face capture with a simple-to-perform passive liveness checking challenge. In this challenge, the user is not required to perform any special actions and is only asked to hold the phone in front of their face. Currently there is only a single subcomponent in this group: BiometricSDKUIFaceModePassiveCore.

• BiometricSDKUIFaceModePassiveCore This is a core component used to implement passive liveness challenge. It contains a complete default user interface needed to perform this challenge. Dependencies: None

BiometricSDKUIFaceModePassive

BiometricSDKUIFaceModePassiveVideo is a group of subcomponents used for face capture with a simple video passive liveness challange. In this challange, user is asked to hold the phone in front of their face in a certain distance and position. The challange is to align their face so that it's image fits inside an oval overlay drawn on the screen. User is being informed in real time to move closer o further from the camera. While user's face is in the correct position capture progress presented on screen is advancing. Currently there is only a single subcomponent in this group: BiometricSDKUIFaceModePassiveVideoCore.

• BiometricSDKUIFaceModePassivVideoeCore This is a core component used to implement passive video liveness challenge. It contains a complete default user interface needed to perform this challenge. Dependencies: None

BiometricSDKUIFaceModeHigh

BiometricSDKUIFaceModeHigh is a group of subcomponents used for face capture with a join the points challenge that requires from the user to connect several random points visible on the screen be performing head movements in various directions depending on the position of displayed points. Subcomponents of this group are:

• BiometricSDKUIFaceModeHighCore This is a core component used for implementing join the points challenge. It can be used separately to easily create a custom join the points user interface if you do not want to use our default join the points user interface. It is also used by our default user interface provided in BiometricSDKUIFaceModeHighJTP3 subcomponent so if you use that default interface then you also need to add this core subcomponent in your project. Dependencies: None

• BiometricSDKUIFaceModeHighJTP3 This is a component which provides our default user interface for join the points challenge. Besides BiometricSDKUIFaceModeHighJTP3, there are older versions of default join the points user interfaces in BiometricSDKUIFaceModeHighJTP2 and BiometricSDKUIFaceModeHighJTP1 components, However, we recommend using the newest version, BiometricSDKUIFaceModeHighJTP3. Dependencies: BiometricSDKUIFaceModeHighCore, Lottie (https://github.com/airbnb/lottie-ios)

• BiometricSDKUIFaceModeHighAnimations This is a component which provides additional, optional animations used by BiometricSDKUIFaceModeHighJTP3. These animations show a face rotating in different directions that might guide the user to pass the join the points challenge. If you do not want to use our face animations for join the points challenge then you do not have to add this subcomponent to your project. Dependencies: None

All challenges listed above with information on how to implement them and customize them in your application with our UIExtensions are described in more detail in further sections of this documentation.

BiometricSDKUIFinger

This framework is responsible for fingerprint images acquisition. It contains graphical components which help extract finger scans. The component has the ability to turn the distance indicator on and off. Moreover, it contains views that inform the user about the proper distance of the fingers from the camera, as well as the progress of the scan.

Framework integration

Note: For face liveness challenges BiometricSDKUIFaceMode* no additional frameworks are required to be integrated, BiometricSDK is enough. Below sections is only for fingerprint image acquisition (BiometricSDKUIFinger framework).

As an integrator you can choose one of two methods of adding UIExtensions to you project: Method 1: This is the recommended option and consists of using cocoapods dependency manager together with cocoapods-art plugin. The cocoapods-art plugin is needed because you must download libraries hosted on our artifactory. Method 2: consists of adding the UIExtensions to your project manually. As mentioned in the components section, UIExtensions are split into a few different components and subcomponents. The procedures for adding different components in your project are generally the same for each of them.

Configuring your project

To use UIExtensions you must add the Privacy - Camera Usage Description (NSCameraUsageDescriptionkey) to the Info.plist as the application will use the camera.

Using Cocoapods

UIExtensions integration with Cocoapods dependency manager (along with cocoapods-art plugin) is the recommended method for integration. Follow these below to integrate UIExtensions in your app:

1. Because standard cocoapods does not support any authentication mechanisms, to use CocoaPods with Artifactory you will must install the 'cocoapods-art' plugin. To install cocoapods-art run the following command:

   Language not specified
   1gem install cocoapods-art

2. The plugin uses authentication as specified in standard .netrc file. If you do not have a .netrc file you must create it in your home directory (in terminal you can do this with cd ~ and touch .netrc commands) and add the following lines with your Artifactory credentials in this file:

   Language not specified
   1machine mi-artifactory.otlabs.fr
   2login ##USERNAME##
   3password ##PASSWORD##

3. Once set, add our Artifactory repository to your cocoapods dependency management system by executing following command:

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

4. At the top of your project Podfile add the following lines which will allow you to use pods from our Artifactory:

   Language not specified
   1plugin 'cocoapods-art', :sources => [
   2  'master', 'smartsdk'
   3]

5. Add chosen UIExtensions components in your Podfile. Below are examples of what you might want to add, depending on your needs:

• To integrate the UI for fingerprint scanning:

  Language not specified
  1pod 'BiometricSDKUIFinger' # Installs fingerprint UIExtension

6. Install specified pods as usual from the terminal:

   Language not specified
   1pod install

NOTE: If you already use our repository, and you cannot resolve some dependency, try to update the specifications with the following command:

Language not specified
1pod repo-art update smartsdk

Manual integration

Instead of using cocoapods dependency manager, it is also possible to integrate UIExtensions manually. However, note that if you choose to integrate the framework manually you cannot update to the new framework version as easily as can be done with cocoapods. You will have to integrate every subcomponent separately (such as core subcomponent, animation subcomponent).

To manually integrate:

1. Download the chosen artifact manually (such as BiometricSDKUIFinger framework) from Artifactory and unpack its contents to get the iOS framework.
2. In the project editor, select the target to which you want to add to the framework.
3. Click the General tab at the top of the project editor.
4. In the Frameworks, Libraries and Embedded Content section, click Add (+),
5. Click Add Other below the list to add a file,
6. Find the downloaded framework file and click Open,
7. Repeat the above steps for all frameworks that you want to add.

Passive liveness

The passive liveness challenge checks whether a real person is using a picture to identify themselves instead of a selfie. This challenge does not require any special actions to be taken by the user and our algorithms will detect frauds, such as taking a picture of another picture, without any special interaction needed from the user. During the passive liveness challenge, a person need only keep their phone in front of themselves so it is very easy to perform.

Implementation

UIExtensions provides a default view class named PassiveLivenessCaptureView that is recommended to use to add passive liveness challenge to your application. This view displays a default UI for this challenge and you must create a capture view variable in your view controller. Then use this variable to start capture view at the start of the main view and stop at the end of the main view. The example is ready to use and commented; you can just copy to your project.

Swift
1import UIKit
2import BiometricSDK
3
4class PassiveViewController: UIViewController, FaceCaptureHandlerDelegate {
5
6    @IBOutlet weak var captureView: PassiveLivenessCaptureView!
7
8    var captureHandler: FaceCaptureHandler?
9
10    override func viewDidLoad() {
11        super.viewDidLoad()
12
13        title = "Passive Liveness"
14
15        // optionally you can adjust visual appearance by using appearance proxy as below
16
17        // PassiveLivenessHintsView.appearance().hintsColor = .blue
18        // PassiveLivenessHintsView.appearance().hintsDetailsColor = .red
19        // PassiveLivenessHintsView.appearance().imageTintColor = .green
20        // PassiveLivenessHintsView.appearance().hintsBackgroundColor = .gray
21        // PassiveLivenessHintsView.appearance().faceImage = UIImage(named: "your_custom_face_outline")
22        // CaptureInfoView.appearance().backgroundColor = .red
23        // CaptureInfoView.appearance().counterColor = .green
24        // BlurOverlayView.appearance().blurEffectStrongness = 0.4
25        // BlurOverlayView.appearance().blurColor = UIColor.white.withAlphaComponent(0.3)
26    }
27
28    override public func viewWillAppear(_ animated: Bool) {
29        super.viewWillAppear(animated)
30
31        // STEP 1. In viewWillAppear we should allocate resources, ie. camera
32        captureView.start()
33        createCaptureHandler()
34    }
35
36    override public func viewDidDisappear(_ animated: Bool) {
37        super.viewDidDisappear(animated)
38
39        // STEP 10. In viewDidDisappear we should release resources
40        captureView.stop()
41        captureHandler?.destroy()
42        captureHandler = nil
43    }
44
45    func createCaptureHandler() {
46        // STEP 2. Choose mode you're willing to use and other options
47        // (all options are described in the documentation)
48        let options = FaceCaptureOptions(livenessMode: .passive)
49        options.captureTimeout = TimeInterval(20)
50
51        // STEP 3. Create a capture handler
52        BIOSDK.createFaceCaptureHandler(with: options) { [weak self] (captureHandler, error) in
53            guard let self = self, error == nil, let captureHandler = captureHandler else {
54                print("Cannot create handler, error: \(error?.localizedDescription ?? "-")")
55                return
56            }
57
58            // STEP 4. Set created capture handler
59            self.captureHandler = captureHandler
60            // STEP 5. Set the delegate
61            self.captureHandler?.delegate = self
62            // STEP 6. Set the preview
63            self.captureHandler?.preview = self.captureView.previewView
64            // STEP 7A. Pass information needed before starting the capture to UIExtension.
65            self.captureView.handleCapturePrepared(timeToUnlockHandler: { [weak self] () -> (Int) in
66                // STEP 7B. Pass information about unlock time in case capture is locked.
67                return self.?.captureHandler?.timeToUnlock ?? 0
68            }, completionHandler: { [weak self] in
69                //STEP 7C. Start capturing after UIExtension finished it's work
70                self?.captureHandler?.startCapture()
71            }}
72        }
73    }
74
75    // MARK: - FaceCaptureHandlerDelegate
76
77    // STEP 8. During capturing you'll receive capturing info, they're hints for a user to improve
78    // or make it even possible to finish the face acquisition. You can simply pass it to UIExtension
79    // to handle it in a default way or you can do some additional stuff with it depending on your needs.
80    func receiveBioCaptureInfo(_ info: BIOCapturingInfo, withError error: Error?) {
81        captureView.handleCaptureInfo(info: info, challengeInfo: challengeInfo, error: error)
82    }
83
84    // STEP 9. When capturing is done, this callback returns detected face as BIOFaceImage. You can
85    // pass this information to UIExtension to handle it in a default way (such as display some additional
86    // animation after finish etc.) and after that do some additional stuff with it depending on your needs.
87    func captureFinished(with images: [BIOFaceImage]?, with biometrics: BIOBiometrics?, withError error: Error?) {
88        captureHandler?.preview = nil //Stop updating preview after capture is finished.
89        captureView.handleCaptureFinished(images: images, biometrics: biometrics, error: error) { [weak self] in
90            // For a face capture only one image is returned
91            let image = images?.first
92            let success = image != nil && image!.livenessStatus == .live && error == nil
93
94            // Do something we the final result here, for example convert BIOFaceImage to UIImage and
95            // pass it to a next view controller in your application that can display it
96            let uiImage = success ? UIImage(from: image!) : nil
97            // show a next view controller that displays captured UIImage here
98        }
99    }
100}

After copying the preceding PassiveViewController class to your project, you can push it on your navigation view controller. You receive a working passive liveness challenge with our default UI. As described in the comments in the code above, you can use customization options to adjust the look of our default UI, as explained in more detail in the Customization section.

If you prefer to use our default implementation with minor appearance customization, you can skip to the next section: Customization. If you prefer to create a custom implementation, use the default PassiveLivenessCaptureView class from UI extensions. In addition, you can use only some views — also used in our PassiveLivenessViewController class — from the BiometricSDK framework. By using those views, you can implement the challenge yourself by using those views on your storyboard directly and handling all the presentation logic on your own.

Views that we provide for our passive liveness challenge, which you can use if you want to make your own custom implementation, are listed below:

• PassiveLivenessHintsView - This view displays the overlay with hints to the user. In your custom implementation you will typically place it on top of the view on which you display the image from the camera.
• CaptureInfoView - This view is used for displaying feedback and a timer which in our default implementation is visible on top of the screen.
• BlurOverlayView - This view can be used for blurring the image from the camera. Typically you will place it between the view on which you display the image from the camera and the view that is displaying hints for the user.

For more information about the views and methods listed, see our UIExtensions API Reference.

Customization

The default UI provided by UIExtensions can be customized. Following, you can see the elements that can be customized and code that customize them in your application. The system appearance proxy mechanism is used to control the look of all visible elements.

1. Face outline image color:

   Swift
   1PassiveLivenessHintsView.appearance().imageTintColor = .green

   Face outline custom image:

   Swift
   1PassiveLivenessHintsView.appearance().faceImage = UIImage(named: "your_custom_face_outline")

2. Hint text color:

   Swift
   1PassiveLivenessHintsView.appearance().hintsColor = .blue

3. Countdown and capture feedbacks text color:

   Swift
   1CaptureInfoView.appearance().counterColor = .green

4. Countdown and capture feedbacks view background color:

   Swift
   1CaptureInfoView.appearance().backgroundColor = .red

5. Camera blur strength:

   Swift
   1BlurOverlayView.appearance().blurEffectStrongness = 0.4

   Camera blur tint color:

   Swift
   1BlurOverlayView.appearance().blurColor = UIColor.white.withAlphaComponent(0.3)

6. Hint image color:

   Swift
   1PassiveLivenessHintsView.appearance().imageTintColor = .green

7. Hint text color:

   Swift
   1PassiveLivenessHintsView.appearance().hintsColor = .blue

   Hint details text color visible if hint details are available:

   Swift
   1PassiveLivenessHintsView.appearance().hintsDetailsColor = .red

8. Hints background color:

   Swift
   1PassiveLivenessHintsView.appearance().hintsBackgroundColor = .gray

We recommend placing above code snippets in your viewDidLoad method implementation as visible in the example from the implementation section above.

Translations

UIExtensions allows you to change all the text visible on the screen by using the standard system localization mechanism. We provide a default English translation in our UIExtensions and you can change or localize them for languages you need to support in your application. To change the text you must create a Localizable.strings file in your project. If you are not using it already, go to: Xcode, menu File -> New -> File -> Strings File, and create a new Localizable.strings file. Then enable localization on that file (in File Inspector on the right panel in Xcode, click Localize in the Localization section for the created file). In the strings file, you can place the localized texts for given keys as usual. Following is a list of all supported keys with their default English translation provided in our UIExtension in the Passive Liveness challenge. If you need to translate them to another language, copy the content listed to your strings file and edit the values for the provided keys.

Swift
1"com.idemia.smartsdk.UIExtensions.passive.info.noTappingNeeded" = "No tapping needed.";
2"com.idemia.smartsdk.UIExtensions.passive.info.useHead" = "Use your head to interact.";
3"com.idemia.smartsdk.UIExtensions.passive.info.centerYourFace" = "Center\nyour\nface";
4"com.idemia.smartsdk.UIExtensions.passive.info.centerYourFaceInCameraView" = "Center your face in camera view";
5"com.idemia.smartsdk.UIExtensions.passive.info.holdPhoneVertically" = "Please hold your phone vertically.";
6"com.idemia.smartsdk.UIExtensions.passive.info.faceInGoodPosition" = "Face is in good position";
7"com.idemia.smartsdk.UIExtensions.passive.info.standStill" = "Stand still for a moment";
8"com.idemia.smartsdk.UIExtensions.passive.info.dontMoveYourPhone" = "Don't move your phone";
9"com.idemia.smartsdk.UIExtensions.passive.info.headMovingTooFast" = "Moving too fast";
10"com.idemia.smartsdk.UIExtensions.passive.info.comeBackInCameraField" = "Come back in the camera field";
11"com.idemia.smartsdk.UIExtensions.passive.info.moveForwards" = "Move your face forward";
12"com.idemia.smartsdk.UIExtensions.passive.info.moveBackwards" = "Move your face backward";
13"com.idemia.smartsdk.UIExtensions.passive.info.pleaseWaitForTime" = "Please wait for:\n{time}";
14"com.idemia.smartsdk.UIExtensions.passive.info.countdownWithSeconds" = "Countdown... {seconds}";
15"com.idemia.smartsdk.UIExtensions.passive.info.capturingStayStill" = "Capturing... stay still";

Note: Some strings in our translations, for example Countdown... {seconds}, contain a placeholder {variable} to display some data inside translated strings. These should be kept in the original, untranslated form in case you translate them to another language.

Passive video liveness

The passive video liveness challenge checks whether a real person is using a picture to identify themselves instead of a selfie. This challange requires user to perform a simple challange such as allignig his face within the oval presented on screen. User is being informed in real time if his face is too far or to close to the camera. While aligned correctly a progress wheel is displayed and a short video of user's face is being recorded. This video is analysed by our algorithms to detect frauds. This challange is only slightly more demanding than the one in the passive liveness mode but it is really quick and simple to succeed.

Implementation

UIExtensions provides a default view class named PassiveVideoLivenessCaptureView that is recommended to use to add passive liveness challenge to your application. This view displays a default UI for this challenge and you must create a capture view variable in your view controller. Then use this variable to start capture view at the start of the main view and stop at the end of the main view. The example is ready to use and commented; you can just copy to your project.

Swift
1import BiometricSDK
2
3class PassiveVideoViewController: UIViewController, FaceCaptureHandlerDelegate, BIOPassiveVideoProtocol {
4    override public func viewWillAppear(_ animated: Bool) {
5        super.viewWillAppear(animated)
6
7        // STEP 1. In viewWillAppear we should allocate resources, ie. camera
8        captureView.start()
9        createCaptureHandler()
10    }
11
12    override public func viewDidDisappear(_ animated: Bool) {
13        super.viewDidDisappear(animated)
14
15        // STEP 10. In viewDidDisappear we should release resources
16        captureView.stop()
17        captureHandler?.destroy()
18        captureHandler = nil
19    }
20
21    func createCaptureHandler() {
22        // STEP 2. Choose mode you're willing to use and other options (all options are described in the documentation)
23        let options = FaceCaptureOptions(livenessMode: .passiveVideo)
24        options.captureTimeout = TimeInterval(20)
25
26        // STEP 3. Create a capture handler
27        BIOSDK.createFaceCaptureHandler(with: options) { [weak self] (captureHandler, error) in
28            guard let self = self, error == nil, let captureHandler = captureHandler else {
29                print("Cannot create handler, error: \(error?.localizedDescription ?? "-")")
30                return
31            }
32
33            // STEP 4. Set created capture handler
34            self.captureHandler = captureHandler
35            // STEP 5. Set the delegate
36            self.captureHandler?.delegate = self
37            // STEP 6. Set the preview
38            self.captureHandler?.preview = self.captureView.previewView
39            // STEP 7A. Pass information needed before starting the capture to UIExtension.
40            self.captureView.handleCapturePrepared(timeToUnlockHandler: { [weak self] () -> (Int) in
41                // STEP 7B. Pass information about unlock time in case capture is locked
42                return self?.captureHandler?.timeToUnlock ?? 0
43            }, completionHandler: { [weak self] in
44                // STEP 7C. Start capturing after UIExtension finished it's work
45                self?.captureHandler?.startCapture()
46            })
47        }
48    }
49
50    // MARK: - FaceCaptureHandlerDelegate
51
52    // STEP 8. During capturing you'll receive capturing info, they're hints for a user to improve or make it even possible to finish the face acquisition. You can simply pass it to UIExtension to handle it in a default way or you can do some additional stuff with it depending on your needs.
53    func receiveBioCaptureInfo(_ info: BIOCapturingInfo, withError error: Error?) {
54        captureView.handleCaptureInfo(info: info, error: error)
55    }
56
57    // STEP 9. When capturing is done, this callback returns detected face as BIOFaceImage. You can pass this information to UIExtension to handle it in a default way (such as display some additional animation after finish etc.) and after that do some additional stuff with it depending on your needs.
58    func captureFinished(with images: [BIOFaceImage]?, with biometrics: BIOBiometrics?, withError error: Error?) {
59        captureHandler?.preview = nil // Stop updating preview after capture is finished
60        captureView.handleCaptureFinished(images: images, biometrics: biometrics, error: error) { [weak self] in
61            // For a face capture only one image is returned
62            let image = images?.first
63            let success = image != nil && error == nil // && image!.livenessStatus == .live
64
65            let vc = ResultViewController()
66            vc.success = success
67            vc.image = success ? UIImage(from: image!) : UIImage(named: "invalid")
68            self?.navigationController?.pushViewController(vc, animated: true)
69        }
70    }
71
72    // MARK: - BIOPassiveVideoProtocol
73
74    func passiveVideoPreparationDidStart() {
75        captureView.handlePreparationStarted()
76    }
77
78    func passiveVideoOverlayDidUpdate(_ overlaySize: CGSize, andPosition position: CGPoint, orError error: Error) {
79        captureView.handleOverlayDidUpdate(overlaySize, andPosition: position)
80    }
81
82    func passiveVideoProgressDidUpdate(_ progress: CGFloat, orError error: Error) {
83        captureView.handleProgress(progress)
84    }
85
86    func passiveVideoPreparationDidEnd() {
87        captureView.handlePreparationEnded()
88    }
89}

After copying the preceding PassiveVideoViewController class to your project, you can push it on your navigation view controller. You receive a working passive liveness challenge with our default UI. As described in the comments in the code above, you can use customization options to adjust the look of our default UI, as explained in more detail in the Customization section.

If you prefer to use our default implementation with minor appearance customization, you can skip to the next section: Customization. If you prefer to create a custom implementation, use the default PassiveVideoLivenessCaptureView class from UI extensions. In addition, you can use only some views — also used in our PassiveVideoLivenessViewController class — from the BiometricSDK framework. By using those views, you can implement the challenge yourself by using those views on your storyboard directly and handling all the presentation logic on your own.

Views that we provide for our passive liveness challenge, which you can use if you want to make your own custom implementation, are listed below:

• PassiveVideoLivenessHintsView - This view displays the overlay with hints to the user. In your custom implementation you will typically place it on top of the view on which you display the image from the camera.
• PassiveVideoLoadingView - This view is used for displaying screen with progress indicator while capture is being prepared. Colors and indicator's element widths can be customized.
• LoadingIndicatorView - This view can be used for showing custom spinning indicator. Can be typically used on screens when it is required for user to wait.
• FaceOvalImageView - This view can be used to present a result image of a succesfull capture.

For more information about the views and methods listed, see our UIExtensions API Reference.

Customization

The default UI provided by UIExtensions can be customized. Following, you can see the elements that can be customized and code that customize them in your application. The system appearance proxy mechanism is used to control the look of all visible elements.

1. Face overlay background color:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().overlayColor = .blue

2. Face overlay opacity:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().overlayOpacity = 0.5

3. Face overlay line width:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().progressLineWidth = 12

4. Face overlay progress line color:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().progressColor = .blue

5. Face overlay progress line background color:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().progressBackgroundColor = .blue

6. Feedback text color:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().feedbackTextColor = .green

7. Feedback text font:

   Swift
   1PassiveVideoLivenessCaptureView.appearance().feedbackFont = UIFont.systemFont(ofSize: 22)

Capture preparation screen

8. Capture preparation screen - title font:

   Swift
   1PassiveVideoLoadingView.appearance().titleFont = UIFont.systemFont(ofSize: 18, weight: .bold)

9. Capture preparation screen - title color:

   Swift
   1PassiveVideoLoadingView.appearance().titleColor = .blue

10. Capture preparation screen - subtitle font:

Swift
1PassiveVideoLoadingView.appearance().subTitleFont = UIFont.systemFont(ofSize: 14, weight: .regular)

11. Capture preparation screen - subtitle color:

Swift
1PassiveVideoLoadingView.appearance().subTitleColor = .blue

Loading circle indicator

12. Loading indicator - progress value:

Swift
1LoadingIndicatorView.appearance().progressValue = 0.7

13. Loading indicator - progress color:

Swift
1LoadingIndicatorView.appearance().progressColor = .yellow

14. Loading indicator - progress background color:

Swift
1LoadingIndicatorView.appearance().progressBackgroundColor = .yellow

15. Loading indicator - progress line width:

    Swift
    1LoadingIndicatorView.appearance().progressWidth = 10.0

Hints screen

16. Hint image color:

Swift
1PassiveVideoLivenessHintsView.appearance().imageTintColor = .yellow

17. Hint text color:

Swift
1PassiveVideoLivenessHintsView.appearance().hintsColor = .yellow

18. Hint details text color visible if hint details are available:

Swift
1PassiveVideoLivenessHintsView.appearance().hintsDetailsColor = .yellow

19. Hints background color:

Swift
1PassiveVideoLivenessHintsView.appearance().hintsBackgroundColor = .yellow

We recommend placing these code snippets in your viewDidLoad method implementation as visible in the example from the implementation section above.

Translations

UIExtensions allows you to change all the text visible on the screen by using standard system localization mechanism. We provide default English translation in our UIExtensions and you can change them or localize them for languages that you need to support in your application. To change the text you must create a Localizable.strings file in your project if you are not using it already (in Xcode, go to menu File -> New -> File -> Strings File and create a new Localizable.strings file) and enable localization on that file (in File Inspector on the right panel in Xcode, click Localize in the Localization section for the created file). In that strings file you can put localized text for given keys as usual. Following is a list of all supported keys with their default English translation provided in our UIExtension in the Passive Video Liveness challenge. If you need to translate them to another language, copy the content listed to your strings file and edit the values for provided keys.

Swift
1"com.idemia.smartsdk.UIExtensions.passiveVideo.preparation.title" = "Preparing...";
2"com.idemia.smartsdk.UIExtensions.passiveVideo.preparation.subTitle" = "Please wait a moment.";
3"com.idemia.smartsdk.UIExtensions.passiveVideo.info.noTappingNeeded" = "No tapping needed.";
4"com.idemia.smartsdk.UIExtensions.passiveVideo.info.useHead" = "Use your head to interact.";
5"com.idemia.smartsdk.UIExtensions.passiveVideo.info.positionFaceWithinOval" = "Position your face \nwithin the oval";
6"com.idemia.smartsdk.UIExtensions.passiveVideo.info.holdPhoneVertically" = "Please hold your phone vertically.";
7"com.idemia.smartsdk.UIExtensions.passiveVideo.info.stayWithinOval" = "Great!\nStay within the oval";
8"com.idemia.smartsdk.UIExtensions.passiveVideo.info.dontMoveYourPhone" = "Don't move your phone";
9"com.idemia.smartsdk.UIExtensions.passiveVideo.info.headMovingTooFast" = "Moving too fast";
10"com.idemia.smartsdk.UIExtensions.passiveVideo.info.pleaseWaitForTime" = "Please wait for:\n{time}";
11"com.idemia.smartsdk.UIExtensions.passiveVideo.info.moveForwards" = "Move closer";
12"com.idemia.smartsdk.UIExtensions.passiveVideo.info.moveBackwards" = "Move further";
13"com.idemia.smartsdk.UIExtensions.passiveVideo.info.scanningStayWithinOval" = "Scanning...\nStay within the oval";

Note: Some strings in our translations, for example Countdown... {seconds}, contain a placeholder {variable} to display some data inside translated strings which should be kept in original, untranslated form in case you translate them to another language.

High mode liveness

High mode liveness challenge provides the capability to check whether a real person is taking a picture of himself. This challenge requires from the user to perform a small task. In high mode liveness, the SDK generates random points on the screen called target points. the user needs to keep the phone in front of them and is asked to turn their head in random directions according to points positions on the screen. The SDK will track the user's head position and check if they properly moved it in order to connect target points. Based on the user's interaction, the algorithms will detect if the person engaging in the challenge is a real person. It will detect frauds, such as using a fake picture to pass the challenge.

Implementation

UIExtensions provides a default view controller class named JoinThePoints3ViewController that is recommended to use to add high mode liveness challenge to your application. This view controller displays a default UI for this challenge and you need only pass the data received from our SDK to this view controller to make it work. The recommended method is to make your own subclass of our JoinThePoints3ViewController, create a capture handler, and implement the SDK delegate methods in it. Below is a ready-to-use and detailed view controller implementation that connects our SDK with high mode liveness UIExtension, which can be copied directly into your project.

Swift
1import UIKit
2import BiometricSDK
3
4class JTPViewController: UIViewController, FaceCaptureHandlerDelegate {
5
6    @IBOutlet weak var captureView: JoinThePoints3CaptureView!
7
8    var captureHandler: FaceCaptureHandler?
9
10    override func viewDidLoad() {
11        super.viewDidLoad()
12
13        title = "Join The Points"
14
15        // optionally you can adjust visual appearance by using appearance proxy as below
16
17        // JoinThePoints3HintsView.appearance().hintsColor = .blue
18        // JoinThePoints3HintsView.appearance().hintsDetailsColor = .red
19        // JoinThePoints3HintsView.appearance().imageTintColor = .green
20        // JoinThePoints3HintBubbleView.appearance().textColor = .green
21        // JoinThePoints3HintBubbleView.appearance().font = UIFont.boldSystemFont(ofSize: 20)
22        // JoinThePoints3HintBubbleView.appearance().bubbleColor = .blue
23        // JoinThePoints3HintBubbleView.appearance().shadowOpacity = 0.8
24        // JoinThePoints3HintBubbleView.appearance().shadowRadius = 20
25        // JoinThePoints3HintBubbleView.appearance().shadowOffset = CGSize(width: 10, height: 10)
26        // JoinThePoints3HintBubbleView.appearance().shadowColor = .blue
27        // JoinThePoints3StartPointView.appearance().fillColor = .blue
28        // JoinThePoints3StartPointView.appearance().strokeColor = .green
29        // JoinThePoints3StartPointView.appearance().pointSize = CGSize(width: 60, height: 60)
30        // JoinThePoints3LinkView.appearance().dotRadius = 10
31        // JoinThePoints3LinkView.appearance().dotMaxRadius = 30
32        // JoinThePoints3LinkView.appearance().dotDistance = 14
33        // JoinThePoints3LinkView.appearance().dottedLineFillColor = .blue
34        // JoinThePoints3LinkView.appearance().dottedLineStrokeColor = .green
35        // JoinThePoints3LinkView.appearance().dottedLineStrokeWidth = 5
36        // JoinThePoints3TargetView.appearance().fillColor = .blue
37        // JoinThePoints3TargetView.appearance().progressColor = .green
38        // JoinThePoints3TargetView.appearance().textColor = .red
39        // JoinThePoints3TargetView.appearance().successBackgroundColor = .brown
40        // JoinThePoints3TargetView.appearance().failureBackgroundColor = .orange
41        // JoinThePoints3TargetView.appearance().successImage = UIImage(named: "your_custom_success_image")
42        // JoinThePoints3TargetView.appearance().failureImage = UIImage(named: "your_custom_failure_image")
43        // BlurOverlayView.appearance().blurEffectStrongness = 0.5
44        // BlurOverlayView.appearance().blurColor = UIColor.white.withAlphaComponent(0.3)
45
46        // optionally you can also set custom rotating face animation as below
47        // (use names of animated png or animated gif files in your main bundle
48        // or in assets catalog added as a data asset)
49
50        // JoinThePoints3FaceAnimationView.appearance().upLeftAnimationName = "rotating_face_up_left"
51        // JoinThePoints3FaceAnimationView.appearance().upRightAnimationName = "rotating_face_up_right"
52        // JoinThePoints3FaceAnimationView.appearance().upFrontAnimationName = "rotating_face_up_front"
53        // JoinThePoints3FaceAnimationView.appearance().downLeftAnimationName = "rotating_face_down_left"
54        // JoinThePoints3FaceAnimationView.appearance().downRightAnimationName = "rotating_face_down_right"
55        // JoinThePoints3FaceAnimationView.appearance().downFrontAnimationName = "rotating_face_down_front"
56        // JoinThePoints3FaceAnimationView.appearance().sideLeftAnimationName = "rotating_face_side_left"
57        // JoinThePoints3FaceAnimationView.appearance().sideRightAnimationName = "rotating_face_side_right"
58    }
59
60    override public func viewWillAppear(_ animated: Bool) {
61        super.viewWillAppear(animated)
62
63        // STEP 1. In viewWillAppear we should allocate resources, ie. camera
64        captureView.start()
65        createCaptureHandler()
66    }
67
68    override public func viewDidDisappear(_ animated: Bool) {
69        super.viewDidDisappear(animated)
70
71        // STEP 10. In viewDidDisappear we should release resources
72        captureView.stop()
73        captureHandler?.destroy()
74        captureHandler = nil
75    }
76
77    func createCaptureHandler() {
78        // STEP 2. Choose mode you're willing to use and other options (all options are described in the documentation)
79        let options = FaceCaptureOptions(livenessMode: .high)
80        options.cr2dMode = BIOCr2dMode.path(withNumberOfTargets: 3)
81        options.captureTimeout = TimeInterval(20)
82
83        // STEP 3. Create a capture handler
84        BIOSDK.createFaceCaptureHandler(with: options) { [weak self] (captureHandler, error) in
85            guard let self = self, error == nil, let captureHandler = captureHandler else {
86                print("Cannot create handler, error: \(error?.localizedDescription ?? "-")")
87                return
88            }
89
90            // STEP 4. Set created capture handler
91            self.captureHandler = captureHandler
92            // STEP 5. Set the delegate
93            self.captureHandler?.delegate = self
94            // STEP 6. Set the preview
95            self.captureHandler?.preview = self.captureView.previewView
96            // STEP 7A. Pass information needed before starting the capture to UIExtension.
97            self.captureView.handleCapturePrepared(timeToUnlockHandler: { [weak self] () -> (Int) in
98                // STEP 7B. Pass information about unlock time in case capture is locked
99                   return self?.captureHandler?.timeToUnlock ?? 0
100            }, completionHandler: { [weak self] in
101                // STEP 7C. Start capturing after UIExtension finished it's work
102                   self?.captureHandler?.startCapture()
103             })
104        }
105    }
106
107    // MARK: - FaceCaptureHandlerDelegate
108
109    // STEP 8A. During capturing you'll receive capturing info, they're hints for a user to improve
110    // or make it even possible to finish the face acquisition. You can simply pass it to UIExtension
111    // to handle it in a default way or you can do some additional stuff with it depending on your needs.
112    func receiveBioCaptureInfo(_ info: BIOCapturingInfo, withError error: Error?) {
113        captureView.handleCaptureInfo(info: info, error: error)
114    }
115
116    // STEP 8B. During capturing you'll receive target info, they're are informations about points
117    // which should be joined with the movements of your head. You pass them to UIExtension to handle
118    // it in a default way.
119    func receive(_ target: BIOCr2DTargetInfo?, at index: UInt, outOf numberOfTargets: UInt, withError error: Error?) {
120        captureView.handleTargetInfo(target: target, index: index, numberOfTargets: numberOfTargets, error: error)
121    }
122
123    // STEP 8C. During capturing you'll receive challenge info with pointer position, that is, with
124    // the point position where a user is currently pointing with his head. You pass that to UIExtension
125    // to handle it in a default way.
126    func receive(_ challengeInfo: BIOCr2DChallengeInfo?, withError error: Error?) {
127        captureView.handleChallengeInfo(challengeInfo: challengeInfo, error: error)
128    }
129
130    // STEP 9. When capturing is done, this callback returns detected face as BIOFaceImage. You can
131    // pass this information to UIExtension to handle it in a default way (such as display some additional
132    // animation after finish etc.) and after that do some additional stuff with it depending on your needs.
133    func captureFinished(with images: [BIOFaceImage]?, with biometrics: BIOBiometrics?, withError error: Error?) {
134        captureHandler?.preview = nil // Stop updating preview after capture is finished
135        captureView.handleCaptureFinished(images: images, biometrics: biometrics, error: error) { [weak self] in
136            // For a face capture only one image is returned
137            let image = images?.first
138            let success = image != nil && image!.livenessStatus == .live && error == nil
139
140            // Do something we the final result here, for example convert BIOFaceImage to UIImage and
141            // pass it to a next view controller in your application that can display it
142            let uiImage = success ? UIImage(from: image!) : nil
143            // show a next view controller that displays captured UIImage here
144        }
145    }
146}

After copying above JTPViewController class to your project you can just push it on your navigation view controller and you will have a working high mode liveness challenge with our default UI. As in the comments in the code above, you can use customization options to adjust the look of our UI, which is explained in the Customization section.

If you simply want to use our default implementation with maybe only some additional minor customization of its appearance then you can skip to the next section of this documentation, Customization. However, if you want to create a custom implementation instead of using default JoinThePoints3CaptureView class from UI extensions you can also use only some views, which are used by our JoinThePoints3ViewController class, from BiometricSDK framework. You can implement the challenge yourself by using those views on your storyboard directly and handling all the presentation logic.

Views for our high mode liveness challenge to make your own custom implementation are listed:

• JoinThePoints3FaceAnimationView - This view displays the animated face that moves in various directions. In your custom implementation, place it on top of the view that displays the image from the camera.
• JoinThePoints3HintsView - This view displays the overlay that presents hints to the user. In your custom implementation, place it above the view that displays the image from the camera and above face animation view.
• JoinThePoints3View - This view displays the points and links on the screen. In your custom implementation, place it between face animation view and hints view.
• BlurOverlayView - This view can be used for blurring the image from the camera. Place it on top of the view on which you display the image from the camera.

For more information about the views and methods listed, refer to our UIExtensions API Reference.

Note 1: Besides JoinThePoints3ViewController in other subcomponents, we provide older JoinThePoints2ViewController and JoinThePointsViewController classes. Those are previous versions of our UI for high mode liveness challenge. We still provide them to our integrators and you use them in the same way as JoinThePoints3ViewController. However, we recommend using the latest version of our UI provided in JoinThePoints3ViewController.

NOTE 2: High mode liveness is the most difficult mode to implement by yourself. For this challenge, we also expose some additional lower level views and protocols. The integrator can use them to achieve more custom implementation of this type of challenge; that is: ChallengeView, ChallengeStartPoint, ChallengeTarget, challengeLink, ChallengePointer. If you want to make a custom look from this type of challenge, you can check those classes in our API Reference.

Customization

The default UI provided by UIExtensions can be customized. Following, you can see which elements can be customized and code that customize them in your application. The system appearance proxy mechanism is used to control the look of all visible elements.

1. Face outline custom animated gifs or animated pngs file names for each direction:

   Swift
   1JoinThePoints3FaceAnimationView.appearance().upLeftAnimationName = "your_custom_rotating_face_up_left"
   2JoinThePoints3FaceAnimationView.appearance().upRightAnimationName = "your_custom_rotating_face_up_right"
   3JoinThePoints3FaceAnimationView.appearance().upFrontAnimationName = "your_custom_rotating_face_up_front"
   4JoinThePoints3FaceAnimationView.appearance().downLeftAnimationName = "your_custom_rotating_face_down_left"
   5JoinThePoints3FaceAnimationView.appearance().downRightAnimationName = "your_custom_rotating_face_down_right"
   6JoinThePoints3FaceAnimationView.appearance().downFrontAnimationName = "your_custom_rotating_face_down_front"
   7JoinThePoints3FaceAnimationView.appearance().sideLeftAnimationName = "your_custom_rotating_face_side_left"
   8JoinThePoints3FaceAnimationView.appearance().sideRightAnimationName = "your_custom_rotating_face_side_right"

2. Starting point fill color:

   Swift
   1JoinThePoints3StartPointView.appearance().fillColor = .blue

   Starting point stroke color:

   Swift
   1JoinThePoints3StartPointView.appearance().strokeColor = .green

   Starting point size:

   Swift
   1JoinThePoints3StartPointView.appearance().pointSize = CGSize(width: 60, height: 60)

3. Link dot minimum radius:

   Swift
   1JoinThePoints3LinkView.appearance().dotRadius = 10

   Link dot maximum radius:

   Swift
   1JoinThePoints3LinkView.appearance().dotMaxRadius = 30

   Distance between link dots:

   Swift
   1JoinThePoints3LinkView.appearance().dotDistance = 14

   Link dot fill color:

   Swift
   1JoinThePoints3LinkView.appearance().dottedLineFillColor = .blue

   Link dot stroke color:

   Swift
   1JoinThePoints3LinkView.appearance().dottedLineStrokeColor = .green

   Link dot stroke width:

   Swift
   1JoinThePoints3LinkView.appearance().dottedLineStrokeWidth = 5

4. Successfully connected target point color:

   Swift
   1JoinThePoints3TargetView.appearance().successBackgroundColor = .brown

   Successfully connected target point image:

   Swift
   1JoinThePoints3TargetView.appearance().successImage = UIImage(named: "your_custom_success_image")

   Not connected (after failing the challenge, for example due to timeout) target point color:

   Swift
   1JoinThePoints3TargetView.appearance().failureBackgroundColor = .orange

   Not connected (after failing the challenge, for example due to timeout) target point image:

   Swift
   1JoinThePoints3TargetView.appearance().failureImage = UIImage(named: "your_custom_failure_image")

5. Target point fill color:

   Swift
   1JoinThePoints3TargetView.appearance().fillColor = .blue

   Target point progress color:

   Swift
   1JoinThePoints3TargetView.appearance().progressColor = .green

   Target point text color:

   Swift
   1JoinThePoints3TargetView.appearance().textColor = .red

6. Hint bubble color:

   Swift
   1JoinThePoints3HintBubbleView.appearance().bubbleColor = .blue

   Hint bubble text color:

   Swift
   1JoinThePoints3HintBubbleView.appearance().textColor = .green

   Hint bubble text font:

   Swift
   1JoinThePoints3HintBubbleView.appearance().font = UIFont.boldSystemFont(ofSize: 20)

   Hint bubble shadow color:

   Swift
   1JoinThePoints3HintBubbleView.appearance().shadowColor = .blue

   Hint bubble shadow opacity:

   Swift
   1JoinThePoints3HintBubbleView.appearance().shadowOpacity = 0.8

   Hint bubble shadow radius:

   Swift
   1JoinThePoints3HintBubbleView.appearance().shadowRadius = 20

   Hint bubble shadow offset:

   Swift
   1JoinThePoints3HintBubbleView.appearance().shadowOffset = CGSize(width: 10, height: 10)

7. Camera blur strength:

   Swift
   1BlurOverlayView.appearance().blurEffectStrongness = 0.4

   Camera blur tint color:

   Swift
   1BlurOverlayView.appearance().blurColor = UIColor.white.withAlphaComponent(0.3)

8. Hint image color:

   Swift
   1JoinThePoints3HintsView.appearance().imageTintColor = .green

9. Hint text color:

   Swift
   1JoinThePoints3HintsView.appearance().hintsColor = .blue

   Hint details text color visible if hint details are available:

   Swift
   1JoinThePoints3HintsView.appearance().hintsDetailsColor = .red

We recommend placing the code snippets in your viewDidLoad method implementation, as visible in the example from the implementation section.

Translations

UIExtensions allows you to change all the text visible on the screen by using standard system localization mechanism. We provide default English translation in our UIExtensions and you can change them or localize them for languages that you need to support in your application. To change the text you must create a Localizable.strings file in your project if you are not using it already (in Xcode, go to menu File -> New -> File -> Strings File and create a new Localizable.strings file) and enable localization on that file (in File Inspector on the right panel in Xcode, click Localize in the Localization section for the created file). In that strings file you can put localized text for given keys as usual. Following is a list of all supported keys with their default English translation provided in our UIExtension in the High Liveness challenge. If you need to translate them to another language, copy the content listed to your strings file and edit the values for provided keys.

Swift
1"com.idemia.smartsdk.UIExtensions.jtp3.challenge.startHere" = "START\nHERE";
2"com.idemia.smartsdk.UIExtensions.jtp3.challenge.moveLineHere" = "Move the line here with your nose";
3"com.idemia.smartsdk.UIExtensions.jtp3.info.pleaseWaitForTime" = "Please wait for:\n{time}";
4"com.idemia.smartsdk.UIExtensions.jtp3.info.noTappingNeeded" = "No tapping needed.";
5"com.idemia.smartsdk.UIExtensions.jtp3.info.useHead" = "Use your head to interact.";
6"com.idemia.smartsdk.UIExtensions.jtp3.info.centerYourFace" = "Center your face";
7"com.idemia.smartsdk.UIExtensions.jtp3.info.centerYourFaceInCameraView" = "Center your face in camera view";
8"com.idemia.smartsdk.UIExtensions.jtp3.info.holdPhoneVertically" = "Please hold your phone vertically.";
9"com.idemia.smartsdk.UIExtensions.jtp3.info.moveHead" = "Move your head to connect the dots";
10"com.idemia.smartsdk.UIExtensions.jtp3.info.standStill" = "Stand still for a moment";
11"com.idemia.smartsdk.UIExtensions.jtp3.info.dontMoveYourPhone" = "Don't move your phone";
12"com.idemia.smartsdk.UIExtensions.jtp3.info.headMovingTooFast" = "Moving too fast";
13"com.idemia.smartsdk.UIExtensions.jtp3.info.comeBackInCameraField" = "Come back in the camera field";
14"com.idemia.smartsdk.UIExtensions.jtp3.info.moveForwards" = "Move your face forward";
15"com.idemia.smartsdk.UIExtensions.jtp3.info.moveBackwards" = "Move your face backward";

Note: Some strings in our translations, for example Please wait for:\n{time}, contain a placeholder {variable} to display some data inside translated strings that should be kept in original, untranslated form in case you translate them to another language.

Finger scanning

The component is responsible for extracting high-quality fingerprint scans. The user is continuously informed about the progress of the scan and receives information about the distance of the fingers from the camera through an indicator located on the left side of the screen. Additionally, information may appear across the entire screen, assisting during the entire process. It informs whether the user's fingers are too far or too close.

Implementation

To implement fingeprint scanning, use the BiometricSDKUIFinger component from our UIExtensions. As described in the integration section, we recommend using cocoapods to integrate UIExtensions. For passive liveness, you must add pod 'BiometricSDKUIFinger' to your Podfile.

BiometricSDKUIFinger provides a default view class named FingerCaptureView. This view displays a default UI for fingerprint scan and you must create a capture view variable in your view controller. The example is ready to use and commented; you can just copy it to your project.

The simplest way to integrate with finger UIExtension.

Swift
1class FingerViewController: UIViewController, FingerCaptureHandlerDelegate {
2    @IBOutlet private var captureView: FingerCaptureView!
3
4    private var captureHandler: FingerCaptureHandler?
5
6    override open func viewDidLoad() {
7        super.viewDidLoad()
8
9        title = "Finger Capture"
10    }
11
12
13    override func viewWillAppear(_ animated: Bool) {
14        super.viewWillAppear(animated)
15
16        // STEP 1. In viewWillAppear we should allocate resources, ie. camera
17        captureView.reset()
18        startCapture(handSide: .left)
19    }
20
21    override func viewDidDisappear(_ animated: Bool) {
22        super.viewDidDisappear(animated)
23
24        // STEP 15. In viewDidDisappear we should release resources
25        captureHandler?.destroy()
26        captureHandler = nil
27    }
28
29    func startCapture(handSide: BIOHand) {
30        // STEP 2. Choose which mode you’re willing to use and other options (all options are described in the documentation)
31        let options = FingerCaptureOptions(mode: .fingers, hand: handSide)
32        options.captureTimeout = 10
33        options.overlay = .OFF
34        options.livenessType = .medium
35
36        // STEP 3. Create a capture handler
37        BIOSDK.createFingerCaptureHandler(with: options) { [weak self] bioCaptureHandler, error in
38            guard let self = self else {
39                return
40            }
41            guard let captureHandler = bioCaptureHandler, error == nil else {
42                return
43            }
44
45            // STEP 4. Set created capture handler
46            self.captureHandler = captureHandler
47            // STEP 5. Set the delegate
48            self.captureHandler?.delegate = self
49            // STEP 6. Set the preview
50            self.captureHandler?.preview = self.captureView.previewView
51            // STEP 7. Start capturing
52            self.captureHandler?.startCapture()
53
54            // Part UIExtension settings
55            // STEP 8. Set distance indicator range
56            let range = DistanceBarRange(from: captureHandler.captureDistanceRange())
57            // STEP 9. Set distance indicator settings
58            let settings = DistanceIndicatorSettings(with: range)
59            // STEP 10. Start UIExtension
60            self.captureView.start(with: settings, duration: captureHandler.fullCaptureTime())
61        }
62    }
63
64    // STEP 11. When capturing, you will receive finger tracking information that serves as hints for users to improve or facilitate the process of acquiring facial data. You also have the option to pass this information to UIExtension, which will handle it in a default manner, or you can choose to perform additional actions based on your specific requirement.
65    internal func fingerCaptureReceivedTrackingInfo(_ trackingInfo: [FingerTrackingInfo]?, withError error: Error?) {
66        captureView.handle(trackingInfo: trackingInfo)
67    }
68
69    // STEP 12. During capturing you'll receive information about current distance of fingers. It helps to get high quality fingerprints. You can simply pass it to UIExtension to handle it in a default way or you can do some additional stuff with it depending on your needs.
70    func fingerCaptureReceivedCurrentDistance(_ distance: FingerCaptureCurrentDistance) {
71        captureView.handle(distance: distance.value)
72    }
73
74     // STEP 13. During capturing you'll get helpful infromation from FingerCaptureInfo about position. It improves user experience and gives better feedback about fingerprint scan. You can simply pass it to UIExtension to handle it in a default way or you can do some additional stuff with it depending on your needs.
75
76    func fingerCaptureReceivedFeedback(_ info: FingerCaptureInfo) {
77        captureView.handle(feedback: info)
78    }
79
80    // STEP 14A. When capturing is done, this callback returns detected fingerprints as BIOImage array and capture result info.
81    func capturedFingers(_ images: [BIOImage]?, with captureInfo: BIOFingerCaptureInfo?, withError error: Error?) {
82        let image = images?.first
83        let success = image != nil && error == nil
84
85        let vc = ResultViewController()
86        vc.success = success
87        vc.image = success ? UIImage(from: image!) : UIImage(named: "invalid")
88        navigationController?.pushViewController(vc, animated: true)
89    }
90
91    // STEP 14B. When capturing failed, this callback returns the error describing failure reason.
92    func captureFinishedWithError(_ error: Error?) {
93        let vc = ResultViewController()
94        vc.success = false
95        vc.image = UIImage(named: "invalid")
96        navigationController?.pushViewController(vc, animated: true)
97    }
98}