Beginner's Guide for Capture SDK 

This document is intended for developers, integrators, and architects who aim to build and integrate with the IDEMIA toolkit. It describes the high-level features and components of the SampleApp solution by IDEMIA.

SampleApp is an app provided in source code that includes an integration of the Biometric Capture and Document Capture SDKs. The SDK integration developer can copy and paste the SampleApp code, and adapt it for their context (such as personalizing the splash screen), allowing them to speed up the implementation, and to quickly arrive at a workable app with a well-designed UX.

Note: This guide does not include all the methods for integrating the SDKs. For more detailed information about SDK integration, see the iOS Integration Guide.

Overview 

Capture SDK by IDEMIA provides one toolkit for different identity management procedures.

Key features 

  • ID capture and Verification - Verifying the customer identity documents (ID) in real time.

  • Identity Verification - Trusting the customer identity.

  • Biometric Authentication - Simple and secure biometric authentication.

Complete Release Notes are available for each release.

Getting started 

In this guide we present steps to get started with the Capture SDK framework in your own project.

Prerequisites 

  1. To build a project using the Capture SDK for iOS, you need version 15 or later of Xcode.

  2. Developers with knowledge of Objective-C or Swift

  3. Configured project in Xcode (turn off BitCode and add Privacy - Camera Usage)

  4. CocoaPods - optional

  5. JSON file with capture configuration - optional (can be requested from CaptureSDK team)

Download sample applications 

Downloadable sample apps are here:

Configuring your project in Xcode 

Add the Privacy - Camera Usage Description (NSCameraUsageDescriptionkey) to the Info.plist because the app uses the camera.

Installing the SDK 

Use CocoaPods (with Artifactory plugin)

  1. Add Gemfile to your project, with the following dependencies:
Ruby
1gem 'cocoapods'
2gem 'cocoapods-art'

Note: We recommend using Bundler to manage your Ruby dependencies, but if you do not have the CocoaPods with the Artifactory plugin installed already, you can also get them with Bundler or Gemfile using these commands in your terminal:

Shell
1gem install cocoapods
2gem install cocoapods-art

We recommend using Cocoapods 1.13.x or newer and cocoapods-art 1.1.x or newer for the best compatibility.

  1. The plugin uses authentication as specified in a standard .netrc file. In case you're creating an Artifactory account (your Artifactory credentials can be found in: Dashboard > Identity Proofing > Developer > Artifactory > Secrets > Artifactory), contact the Client IDEMIA department with:
Language not specified
1machine mi-artifactory.otlabs.fr
2 login ##USERNAME##
3 password ##PASSWORD##
  1. Once set, add our repository to your CocoaPod's dependency management system:
Shell
1bundle exec pod repo-art add smartsdk 'https://mi-artifactory.otlabs.fr/artifactory/api/pods/smartsdk-ios-local'
  1. At the top of your project Podfile add:
Ruby
1source 'https://cdn.cocoapods.org/'
2
3plugin 'cocoapods-art', :sources => [
4 'smartsdk' # so it could resolve Biometric Capture SDK dependency
5]

Note: Explicit source is required to correctly resolve Cocoapods' master repository when cocoapods-art plugin is used.

  1. Add the Capture SDK in your Podfile in one of its pod's version:
Ruby
1pod 'BiometricSDK' # Full version of the SDK, contains biometrics & documents features |
2pod 'BiometricSDK-biometry' # Contains only biometrics features
3pod 'BiometricSDK-document' # Contains only document features
  1. Then you can use install:
Shell
1bundle exec pod install

Note: If you are already using our repository, and you cannot resolve some dependencies, try to update the specs with:

Shell
1bundle exec pod repo-art update smartsdk

Manually

  1. Download the artifact manually from the artifactory:
  1. In the project editor, select the target to which you want to add a library or framework.

  2. Click Build Phases at the top of the project editor.

  3. Open Embedded Binaries.

  4. Click Add (+).

  5. Click Add Other below the list.

  6. Add the following items:

    • BiometricSDK.framework
    • (optionally for face capture) BiometricSDKFaceCapturePluginNormal.framework (or other face capturing plugin)
    • (optionally for face capture) BiometricSDKAlgorithmPlugin_F6_5_LOW70.framework (or other matching algorithm plugin)
    • (optionally for finger capture new API) FingerCaptureSDK.framework
    • (optionally for finger capture new API) BiometricSDKUIFinger.framework

Configuration 

This section describes how to set up a basic configuration for your Capture SDK app by function. Additionally, it describes configurable parameters for each function.

DocumentCapture handler objects 

This section describes parameters that configure the Document Capture handler behavior of properties such as mode, camera, flash, timeout, building overlay, or log level.

Value
Type
Description
captureModeEnumThe enum option to configure DocumentCaptureMode.
rectificationBooleanDefines if rectification is enabled or disabled (according to photos).
cameraEnumCamera option to configure BioCapture.
torchEnumOBSOLETE. Torch option to configure BioCapture.
overlayEnumOverlay option to configure BioCapture.
captureTimeoutIntegerCapture timeout in seconds.
logLevelEnumLevel of logs that are displayed during debug.
orientationEnumDefines the orientation of the capture.
dumpFileEnableBooleanDefines if logs are created or not.
dumpFileFolderStringDefines the folder where the logs are saved. Default location is the Documents folder.
videoRecordEnableBooleanDefines if partial dump video recording is enabled or not.
videoRecordFolderStringDefines the folder where partial dump video recordings are saved.
minDPIIntegerMinimum DPI for a datapage. This parameter defines how close the document should be to the camera.
acquisitionQualityLevelEnumCriterion of document autocapture restrictiveness towards imperfections. The higher it is set, the higher the acquisition time is.
stillShootEnabledBooleanDefines the way of capturing image: high quality video or photo.

Other Values

  • enum: [DocumentCaptureModeReadMRZ, DocumentCaptureModeMRZImageMedium, DocumentCaptureModeBarcode, DocumentCaptureModePDF417, DocumentCaptureModeBarcodeVeryLowID1, DocumentCaptureModeVeryLowID1, DocumentCaptureModeMRZMediumVeryLowID]

  • enum: [BIOCameraFront, BIOCameraRear]

  • enum: [BIOOverplayOFF, BIOOverlayON]

    • default: 120
  • enum: [BIOLogLevelNone, BIOLogLevelDebug, BIOLogLevelInfo, BIOLogLevelWarning, BIOLogLevelError]

  • enum: [BIOOrientationLandscapeLeft, BIOOrientationLandscapeRight, BIOOrientationLandscapePortrait, BIOOrientationUpSiteDown]

    • values: enable, disable
    • default: nil
    • range: 1 to 400
    • default: 360
  • enum: [BIODocumentAcquisitionQualityLevelHigh, BIODocumentAcquisitionQualityLevelMedium, BIODocumentAcquisitionQualityLevelLow]

    • default: NO

FaceCapture handler objects 

This section describes parameters that configure the Face Capture handler behavior of properties such as camera, flash, timeout, building overlay, and log level.

Value
Type
Description
cr2dModeEnumChooses the CR2D mode.
challengeInternalDelayIntegerSets the time interval between challenges of capturing the document.
maxCapturesBeforeDelayIntegerDefines the maximum number of captures before locking the capture for a certain delay. (Default: 5). It can be set to -1 to disable locking based on repeated failed captures.
timeCaptureDelayArrayIntegerDefines an array of capture delays for each lock that occurs after number of captures configured with maxCapturesBeforeDelay. First lock after maxCapturesBeforeDelay lasts the number of seconds defined in the first element of timeCaptureDelayArray, second lock lasts the number of seconds defined in the second element, and so on. For all capture attempts after the array length, the last element of the array is used. All values are in seconds. Default values: [1 * 60, 5 * 60, 15 * 60, 60 * 60]).
illuminationEnabledBoolean(OBSOLETE) Defines if the illumination check is enabled or disabled.
timeCaptureDelayInteger(DEPRECATED) Sets the capture delay in milliseconds for each lock.
timeCaptureDelayMultiplierInteger(DEPRECATED) Sets the capture delay multiplier for each lock.
cameraEnumCamera option to configure BioCapture.
torchEnumOBSOLETE. Torch option to configure BioCapture.
overlayEnumOverlay option to configure BioCapture.
captureTimeoutIntegerCapture timeout in seconds.
logLevelEnumDefines the level of the system logs.
orientationEnumDefines the orientation of the capture.
previewColorspaceEnumSets the colorspace of the camera preview.
dumpFileEnableBooleanDefines if logs are created or not.
dumpFileFolderStringDefines where the logs are saved. Default location is the Documents folder.
videoRecordEnableBooleanDefines if video recording is enabled or not.
videoRecordFolderStringDefines the folder where the video recordings are saved.
partialDumpVideoRecordEnableBooleanDefines if partial dump video is recorded or not.
partialDumpVideoRecordFolderStringDefines the folder where partial dump video recordings are saved.
challengeIntervalDelayIntegerDefines the time interval delay (in seconds) between challenges.

Other Values:

  • default: FaceCaptureLivenessModePassive
  • enum: [FaceCaptureLivenessModeActive, FaceCaptureLivenessModeNoLiveness, FaceCaptureLivenessModePassive, FaceCaptureLivenessModePassiveVideo]

    • default: BIORandomCr2dMode
  • enum: [BIORandomCr2dMode, BIOFixedTargetCr2dMode, BIOPathCr2dMode]

    • default: NO for FaceCaptureModeChallengeCr2d[Low|Medium|High]
    • default: 4
    • default: BIOCameraFront
  • enum: [BIOCameraFront, BIOCameraRear]

    • default: BIOOverplayOFF
  • enum: [BIOOverplayOFF, BIOOverlayON]

    • default: 120
  • enum: [BIOLogLevelDebug, BIOLogLevelInfo, BioLogLevelWaring, BIOLogLevelError, BioLogLevelNone]

  • enum: [BIOPreviewColorspaceColor, BIOPreviewColorspaceColorBlur, BIOPreviewColorspaceGray, BIOPreviewColorspaceGrayBlur, BIOPreviewColorspaceGrayBlurBordered]

    • values: enable, disable
    • default: nil

FingerCapture handler objects 

This section describes parameters which can configure the Finger Capture handler behavior of properties such as camera, flash, timeout, building overlay, and log level.

Value
Type
Description
bioCaptureModeEnumChooses finger capture mode.
referenceTemplatesStringList of reference templates to be used in fast authentication mode.
thresholdIntegerThreshold value for the authentication to succeed.
handEnumSpecifies which hand is being scanned.
amputatedFingersBitmaskSpecifies which fingers are missing.
maxNumberOfCapturesInteger(OBSOLETE) Number of capture verifications to be performed to ensure high quality images.
cameraEnumCamera option to configure BioCapture.
torchEnumOBSOLETE. Torch option to configure BioCapture.
overlayEnumOverlay option to configure BioCapture.
captureTimeoutIntegerCapture timeout in seconds.
logLevelEnumDefines the level of system logs.
orientationEnumDefines the orientation of the capture.
previewColorspaceEnumSets the colorspace of the camera preview.
dumpFileEnableBooleanDefines if logs are created or not.
dumpFileFolderStringDefines where the logs are saved. Default location is the Documents folder.
videoRecordEnableBooleanDefines if video recording is enabled or disabled.
videoRecordFolderStringDefines the folder where video recordings are saved.
partialDumpVideoRecordEnableBooleanDefines if partial dump video is recorded or not.
partialDumpVideoRecordFolderStringDefines the folder where partial dump video recordings are saved.
challengeIntervalDelayIntegerDefines the time interval delay (in seconds) between challenges.
livenessTypeEnumDefines the liveness check type.
UHDResolutionEnabledBooleanDefines if camera should use UHD/4K resolution. If the camera does not support UHD/4K resolution, it uses the highest available resolution.

Other Values:

  • enum: [FingerCaptureModeFingers, FingerCaptureModeThumb, FingerCaptureModeAuthentication]

    • recommended: 3500
    • default: 1
    • recommendation: 3
    • default: BIOCameraFront
  • enum: [BIOHandRight, BIOHandLeft]

  • bitmask: [ BIOAmputatedFingerNone, BIOAmputatedFingerIndex, BIOAmputatedFingerMiddle, BIOAmputatedFingerRing, BIOAmputatedFingerLittle]

  • enum: [BIOCameraFront, BIOCameraRear]

  • enum: [BIOOverplayOFF, BIOOverlayON]

    • default: 120
  • enum: [BIOLogLevelDebug, BIOLogLevelInfo, BioLogLevelWarning, BIOLogLevelError, BioLogLevelNone]

  • enum: [BIOPreviewColorspaceColor, BIOPreviewColorspaceColorBlur, BIOPreviewColorspaceGray, BIOPreviewColorspaceGrayBlur, BIOPreviewColorspaceGrayBlurBordered]

    • values: enabled, disabled
    • default: nil
  • enum: [FingerCaptureLivenessTypeNoLiveness, FingerCaptureLivenessTypeVeryLow, FingerCaptureLivenessTypeLow, FingerCaptureLivenessTypeMedium]

    • default: FingerCaptureLivenessTypeLow

Architecture 

The SampleApp application consists of independent modules which are reused in particular use cases.

The following figure provides an overview of the ecosystem of the Capture SDK iOS solution. It shows the internal components.

SmartDocSmartBio-iOSBegGuide ind modules

Each one is described in a separate section of this documentation.

  • LicenseManager - Responsible for requesting, storing, and providing the license.

  • FaceCaptureHandler - Responsible for capturing face biometric data.

  • FingerCaptureHandler - Responsible for capturing finger biometric data.

  • BioMatcherHandler - Responsible for biometric coding matching biometric data.

  • DocumentCaptureHandler - Responsible for document scanning functions like reading MRZ documents.

  • BioStoreDB - Responsible for storing all biometric templates.

  • ImageUnits - Responsible for handling the images format conversion.

Enums Attributes Description 

Document Capture Mode 

These enums configure the behavior of Document Capture.

Attribute
Description
DocumentCaptureModeReadMRZReads the MRZ lines.
DocumentCaptureModeMRZImageMediumReads the MRZ lines and retrieves an image from the document. Capture is based on a video stream.
DocumentCaptureModeMRZImageStillMedium(DEPRECATED) Reads MRZ lines and retrieves an image from the document. Capture is based on a still image.
DocumentCaptureModeBarcodeReads a barcode.
DocumentCaptureModeBarcodePDF417Reads a barcode in PDF417 standard.
DocumentCaptureModeBarcodeVeryLowID1Captures an image at the device's best video resolution of a ID1 document with a PDF417-standard barcode.
DocumentCaptureModeVeryLowID1Captures an image at the device's best video resolution of a ID1 document.
DocumentCaptureModeVeryLowIDCaptures an image at the device's best video resolution of ID1, ID2, and ID3 documents.
DocumentCaptureModeMRZMediumVeryLowIDReads the MRZ and captures an image at the device's best video resolution of ID1, ID2, and ID3 documents.

BIOCODEMODE 

This enum gives information concerning the confidence of the information returned.

Attribute
Description
BIOCodedModeNominalThe best image is returned. All video quality criteria have been fulfilled.
BIOCodedModeForceThe user employed the force capture trigger.
BioCodedModeTimeoutThe best image returned on timeout.

BIORECTIFICATION 

This enum enables or disables rectification.

Attribute
Description
BIOORectificationEnableEnables rectification
BIORectificationDisableDisables rectification

BIODOCUMENTACQUISITIONQUALITYLEVEL 

This enum describes the criterion of document autocapture restrictiveness. When the SDK acquires the best possible image, it does it in intervals which fit in a timeout time. Each subsequent interval is less restrictive of imperfections than the previous one.

Attribute
Description
BIODocumentAcquisitionQualityLevelHighWhen set, this tries to get the best image in three intervals, where the first interval is the most restrictive.
BIODocumentAcquisitionQualityLevelMediumWhen set, this tries to get the best image in two intervals, where the first interval is less restrictive then in the high level.
BIODocumentAcqusitionQualityLevelLowWhen set, this tries to get the best image in two first seconds. If a reflection or low light is detected, they are ignored after the first two seconds.

BIOCAPTUREMODE 

This enum is used to configure the behavior of Bio Capture.

Attribute
Description
FaceCaptureLivenessModePassiveVideoFace tracking with passive liveness verification in video mode for the server verification purposes only
FaceCaptureLivenessModePassiveFace tracking with passive liveness verification
FaceCaptureLivenessModeActiveFace tracking using CR2D challenge of liveness
FaceCaptureLivenessModeNoLivenessFace tracking with default sub-profile

BIOCr2dMode 

This is the CR2D mode base class.

BIORANDOMCR2DMODE 

The CR2D mode where the target is fully random.

Objective-C
1FaceCaptureOptions\* options = [[FaceCaptureOptions alloc] initWithLivenessMode:FaceCaptureLivenessModeHigh];
Objective-C
1// [...]
2options.cr2dMode = [BIOCr2dMode random];

BIOFIXEDTARGETCR2DMODE 

This is the CR2D mode where the target has a defined position. The position values x and y are normalized to be independent from the screen dimensions. Both are values between -1.0 through 0.0 to 1.0.

Objective-C
1FaceCaptureOptions\* options = [[FaceCaptureOptions alloc] initWithLivenessMode:FaceCaptureLivenessModeHigh];
2 // [...]
3
4 options.cr2dMode = [BIOCr2dMode random];

BIOPATCHCR2DMODE 

This is a CR2D mode where there is more than one target. The number of the targets is defined be by the targetsNumber parameter.

Objective-C
1FaceCaptureOptions\* options = [[FaceCaptureOptions alloc] initWithLivenessMode:FaceCaptureLivenessModeHigh];
2 // [...]
3 NSInteger numberOfTargets = x;
4 options.cr2dMode = [BIOCr2dMode pathWithNumberOfTargets:numberOfTargets];

License Manager 

Use Cases 

Below is displayed the generic execution flow to be followed to perform the operation when creating or retrieving a valid license.

SmartDocSmartBio-iOSBegGuide usecases

LKMS is the license mechanism supported by the Capture SDK. This is the only licensing that can be used by integrators.

To create a profile for LKMS, the team should provide the following parameters:

  • License Server URL

  • Profile ID

  • API Key

You need to fill the mentioned parameters in LicenseManager.swift which is the main component responsible for retrieving a license.

Open LicenseManager and find LKMS structure.

Code Block 1 LKMS Structure

Swift
1struct LKMS {
2 static let serverEndpointUrl = "<#LKMSv3 server endpoint URL#>"
3 static let profileId = "<#LKMSv3 ProfileID#>"
4 static let apiKey = "<#LKMSv3 ApiKey#>"
5 }

Licenses Required 

Depending on which version of the library is used, the LKMS licenses required are created with features.

Feature
Biometry + Document
Biometry
Document
MORPHOFACSXX
VERIFXX
IDENTXX
MIMAXXX
MSC_COREXXX
MSC_LIVENESSXX

To enable the feature for video dump you will need also: MSC_DUMP.

Face Capture Handler 

Use Cases 

SmartDocSmartBio-iOSBegGuide usecases1

Start Using Face Capture Handler 

  1. Every time before navigating or wanting to use the Capture SDK, make sure there is an active license. The license is checked within the SDK as well, if it's not valid, the SDK will not work.
Swift
1let manager = LicenseManager.provideLicenseManager(
2 profileId: LKMS.profileId,
3 apiKey: LKMS.apiKey,
4 serverUrl: LKMS.serverEndpointUrl
5 )
6 manager.activate { (error: LicenseActivationError) in
7 if let error {
8 // Failed to fetch or activate the license.
9 } else {
10 // License fetched and activated with success.
11 }
12 }
  1. Import the framework module to your view controller.
1#import <BiometricSDK/BiometricSDK.h>
  1. Add at least one UIImageView or subclass to your layout. It will be used to preview the stream from the camera.
1@property (weak, nonatomic) IBOutlet UIImageView *preview;
  1. Prepare the property for retaining the FaceCaptureHandler instance. This object will be handling all operations related to capturing.
1@property (strong, nonatomic) id<FaceCaptureHandler> captureHandler;
  1. Prepare the FaceCaptureOptions object, which contains the capture's configuration. The most important is the liveness mode, which will be used for the capture. More details about the liveness capture modes can be found in the integration guide.
1FaceCaptureOptions *options = [[FaceCaptureOptions alloc] initWithLivenessMode:FaceCaptureLivenessModePassive];
  1. Create the FaceCaptureHandler instance object using the options and retain the handler by setting it to the earlier prepared property.
1[BIOSDK createFaceCaptureHandlerWithOptions:options withCompletionHandler:^(id<FaceCaptureHandler> captureHandler, NSError* error) {
2 if (!captureHandler || error) {
3 NSLog(@"Cannot create the capture handler, error: %@", error);
4 return;
5 }
6 self.captureHandler = captureHandler;
7 ...
8}];
  1. Set the delegate for FaceCaptureHandler.delegate. self has to implement the FaceCaptureHandlerDelegate protocol.
1[BIOSDK createFaceCaptureHandlerWithOptions:options withCompletionHandler:^(id<FaceCaptureHandler> captureHandler, NSError* error) {
2 if (!captureHandler || error) {
3 NSLog(@"Cannot create the capture handler, error: %@", error);
4 return;
5 }
6 self.captureHandler = captureHandler;
7 self.captureHandler.delegate = self;
8 ...
9}];
  1. After FaceCaptureHandler has finished its initialization, the preview view can be set.
1[BIOSDK createFaceCaptureHandlerWithOptions:options withCompletionHandler:^(id<FaceCaptureHandler> captureHandler, NSError* error) {
2 if (!captureHandler || error) {
3 NSLog(@"Cannot create the capture handler, error: %@", error);
4 return;
5 }
6 self.captureHandler = captureHandler;
7 self.captureHandler.delegate = self;
8 self.captureHandler.preview = self.preview;
9 ...
10}];
  1. Now it can start capturing.
1[BIOSDK createFaceCaptureHandlerWithOptions:options withCompletionHandler:^(id<FaceCaptureHandler> captureHandler, NSError* error) {
2 if (!captureHandler || error) {
3 NSLog(@"Cannot create the capture handler, error: %@", error);
4 return;
5 }
6 self.captureHandler = captureHandler;
7 self.captureHandler.delegate = self;
8 self.captureHandler.preview = self.preview;
9 [self.captureHandler startCaptureWithCompletionHandlerError:nil];
10}];
  1. During capturing the SDK will be informing about the events taking place with the delegate's methods:
  • Method receiveBioCaptureInfo:withError: will inform about the capturing status, like a user needs to change a position or an environment is too dark or too light.
1- (void)receiveBioCaptureInfo:(BIOCapturingInfo)info withError:(NSError *)error {
2 if (error) {
3 return;
4 }
5 NSLog(@"Received a capturing info: %@", NSStringFromBIOCapturingInfo(info));
6}
  • Method captureFinishedWithImages:withBiometrics:withError: indicates that the capture has finished. As a result, an image or an error is returned. The image will contain the best frame with a selfie.
1- (void)captureFinishedWithImages:(NSArray<BIOImage *> *)images withBiometrics:(BIOBiometrics *)biometrics withError:(NSError *)error {
2 if (error) {
3 NSLog(@"The capture finished with an error: %@", error);
4 return;
5 }
6 NSLog(@"The capture finished successfully.");
7
8 // Converts BIOImage into UIImage
9 UIImage *capturedImage = [UIImage imageFromBIOImage:images[0]];
10
11 // ...
12}
  1. Whenever the view controller disappears, resources (e.g. camera) need to be released.
1- (void)viewDidDisappear:(BOOL)animated {
2 [super viewDidDisappear:animated];
3 [self.captureHandler destroy];
4 self.captureHandler = nil;
5}

Finger Capture Handler 

Use Cases 

SmartDocSmartBio-iOSBegGuide usecases2

Start Using Finger Capture Handler 

  1. Import the framework header to your view controller.
Swift
1#import <BiometricSDK/BiometricSDK.h>
  1. Add at least one UIImageView or subclass to your layout. It will be used to preview the stream from the camera. It is not necessary for capture to have preview.
Swift
1@property (weak, nonatomic) IBOutlet UIImageView \*preview;
  1. Check your license status.

  2. Verify you have the property for FingerCaptureHandler. This object handles all operations related to capturing.

Swift
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 ...
4 }];
  1. Set the delegate for FingerCaptureHandler to self. self will have to implement the FingerCaptureHandlerDelegate protocol.
Swift
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 ...
5 }];
  1. After FingerCaptureHandler finished its initialization, the preview view can be set.
Swift
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 self.captureHandler.preview = self.preview;
5 ...
6 }];
  1. Now it can start capturing.
Swift
1[BIOSDK createFingerCaptureHandlerWithOptions:options withCompletionHandler:^(id<FingerCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 self.captureHandler.preview = self.preview;
5 [self.captureHandler startCaptureWithCompletionHandlerError:nil];
6 }];
  1. Whenever the view controller disappears, resources, such as the camera, must be released.
Swift
1- (void)viewDidDisappear:(BOOL)animated{
2 [super viewDidDisappear:animated];
3 [self.captureHandler destroy];
4 }

Document Capture Handler 

Use Cases 

SmartDocSmartBio-iOSBegGuide usecases3

Start Using Document Capture Handler 

  1. Import the framework header to your view controller.
Swift
1#import <BiometricSDK/BiometricSDK.h>
  1. Add at least one UIImageView or subclass to your layout. It will be used to preview a stream from camera. It is not necessary for the capture to have a preview.
Swift
1@property (weak, nonatomic) IBOutlet UIImageView *preview;
  1. Check your license status.

  2. Verify that you have the property for DocumentCaptureHandler. This object handles all operations related to capturing.

Swift
1[BIOSDK createDocumentCaptureHandlerWithOptions:options withCompletionHandler:^(id<DocumentCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 ...
4 }];
  1. Set the delegate for DocumentCaptureHandler to self. self will have to implement the DocumentCaptureHandlerDelegate protocol.
Swift
1[BIOSDK createDocumentCaptureHandlerWithOptions:options withCompletionHandler:^(id<DocumentCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 ...
5 }];
6 }
  1. After the DocumentCaptureHandler has finished its initialization, the preview view can be set.
Swift
1[BIOSDK createDocumentCaptureHandlerWithOptions:captureOptions withCompletionHandler:^(id<DocumentCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 self.captureHandler.preview = self.preview;
5 ...
6 }];
  1. Now it can start capturing.
Swift
1[BIOSDK createDocumentCaptureHandlerWithOptions:options withCompletionHandler:^(id<DocumentCaptureHandler> captureHandler, NSError* error) {
2 self.captureHandler = captureHandler;
3 self.captureHandler.delegate = self;
4 self.captureHandler.preview = self.preview;
5 [self.captureHandler startCaptureWithCompletionHandlerError:nil];
6 }];
  1. Whenever the view controller disappears, resources, such as the camera, must be released.
Swift
1- (void)viewDidDisappear:(BOOL)animated{
2 [super viewDidDisappear:animated];
3 [self.captureHandler destroy];
4 }

Capture options from configuration file 

Alternatively, if you own a configuration file provided by the Capture SDK team you can use static method + (instancetype _Nullable)createFromConfigurationFileWithError:(NSError**)error to initialize selected capture options. A configuration file shall be located in an application's bundle resources and be named ConfigurationFile.json. The capture options parameters, which were configured with a configuration file, cannot be changed in the runtime (except for FingerCaptureOptions). Changing these parameters returns an error when creating a handler.

1FaceCaptureOptions *options = [FaceCaptureOptions createFromConfigurationFileWithError:&error];

Bio Match Handler 

SmartDocSmartBio-iOSBegGuide biomatchhandler

Authentication 

This verifies a list of candidate templates against a list of reference templates. Check the use case named Verify.

Objective-C
1BIOAuthenticationOptions* options = [[BIOAuthenticationOptions alloc] initWithModality:BIOModalityFace];
2 [self.matcherHandler authenticateWithOptions:options
3 withBiometricCandidate:biometricCandidate
4 withBiometricReference:biometricReference
5 andCompletionHandler:^(BIOAuthenticationResult* result, NSError* error) {
6 ...
7 ` }];

Identify 

This identifies the list of candidate templates, to which the user belongs, against a list of reference templates. This method can also be used to verify or authenticate users.

Objective-C
1BIOIdentificationOptions* options = [[BIOIdentificationOptions alloc] initWithModality:BIOModalityFace];
2 [matcher identifyWithOptions:options
3 withBiometricCandidate:biometricCandidate
4 withBiometricReferences:biometricReferences
5 andCompletionHandler:(^(BIOIdentificationResult* result, NSError* error){
6 .......
7 }];

Detect Biometric 

This function detects the biometrics in a BIOImage. It is intended as an extractor of all the biometric templates contained in an image (for example all the faces that are in an image).

Objective-C
1BIODetectBiometricOptions* options = [BIODetectBiometricOptions biometricsWithLocation:BIOLocationFaceFrontal
2 withModality:BIOModalityFace];
3 [matcher detectBiometricWithOptions:options
4 withBIOImage:image
5 withCompletionHandler:**void**(^)(NSArray<BIOTemplate*>* templates,
6 NSError* error){
7 .....
8 }];

Bio Store DB 

SmartDocSmartBio-iOSBegGuide biostoreDB

List All Templates 

This lists all the templates stored in the database.

Objective-C
1+(**void**)listTemplatesWithCompletionHandler:(**void**(^)(NSArray<BIOTemplate*>* templates, NSError* error))completionHandler

Finger Sample App description 

The Finger Sample App was created to demonstrate the features of the Capture SDK specifically related to fingerprint biometric capture. It showcases the capabilities of the SDK in handling fingerprint recognition, providing a practical example of how to integrate fingerprint scanning into an application.

Prerequisites 

To build and test this sample application you will need:

  1. Xcode 15 or later (Swift 5 compatible).
  2. Device with iOS 15.0 or later (simulator is not supported).
  3. License data (contact us to get the license). You need profileID and API key.

Sample directory structure 

The Finger Sample App follows a specific directory structure that organizes its components effectively. Below is a detailed explanation of the structure:

alt text

The App Directory 

The App directory contains the main application files, which include an example implementation of the Finger variant of the BiometricSDK. The implementation within this directory is structured to showcase a practical use case of biometric recognition using fingerprint technology, offering a reference point for developers looking to integrate or extend the functionality in their own projects.

The Common Directory 

The Common directory holds various helper classes that provide utility functions necessary for the operation of the sample app. These classes include the implementation of the LicenseManager, which is responsible for managing licensing operations for the BiometricSDK.

Important files 

  1. The AppConfiguration file stores essential credentials used for license activation.
    alt text
  2. The FingerCaptureViewController file has usage of the FingerCaptureHandler. This file demonstrates the process of performing finger scanning, providing developers with a clear guide on how to integrate fingerprint capture into their application. It explains how to use finger and amputee scanning.
    alt text
  3. The LicenseManager file contains an example implementation for handling license activation.
    alt text

Building the application 

  1. Open project workspace in Xcode.
  2. Open AppConfiguration file and fill in license fields in LKMS struct with values provided by Idemia:
    Language not specified
    1enum LKMS {
    2 static let serverEndpointUrl = <The License server endpoint>
    3 static let profileID = <profileID>
    4 static let apiKey = <apiKey>
    5}
    All variables are String type.
  3. Open project settings and select application build target. Make sure that General tab is selected.
    1. In Identity section make sure that Bundle Identifier (PRODUCT_BUNDLE_IDENTIFIER) is set to the APP_ID that you provided to us to generate your license.
    2. In Signing section make sure that your Team (DEVELOPER_TEAM) is selected.
  4. Build and run the project.

Glossary of Terms 

Term
Definition
APIApplication Programming Interface
CocoaPodsApplication level dependency manager
iOSiPhone Operating System
ISOInternational Organization for Standardization
MRZMachine Readable Zone
OCROptical Character Recognition
QR CodeQuick Response Code
SDKSoftware Development Kit
Biometric Capture SDKToolkit for capturing biometric data
Document Capture SDKToolkit for capturing data from documents
UIImageViewAn object that displays a single image or a sequence of animated images in your interface.