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 14.2 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:

• one package with all the apps inside

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.

2. 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##

3. 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'

4. 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.

5. 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

6. 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:

2. In the project editor, select the target to which you want to add a library or framework.

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

4. Open Embedded Binaries.

5. Click Add (+).

6. Click Add Other below the list.

7. Add the following items:

   • BiometricSDK.framework
   • (optionally for face capture) BiometricSDKFaceCapturePluginNormal.framework (or other face capturing plugin)
   • (optionally for face capture) BiometricSDKAlgorithmPlugin_F6_0_IDD80.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.

Other Values

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

• enum: [BIOCameraFront, BIOCameraRear]

• enum: [BIOTorchOFF, BIOTorchON]

• 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.

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]

• enum: [BIOTorchOFF, BIOTorchON]

  • 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.

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: [BIOTorchOFF, BIOTorchON]

• 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.

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.

BIOCODEMODE 

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

BIORECTIFICATION 

This enum enables or disables 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.

BIOCAPTUREMODE 

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

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.

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.

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

Face Capture Handler 

Use Cases 

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    }

2. Import the framework module to your view controller.

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

3. Add at least one UIImageView or subclass to your layout. It will be used to preview the stream from the camera.

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

4. Prepare the property for retaining the FaceCaptureHandler instance. This object will be handling all operations related to capturing.

Objective-C
Swift
1@property (strong, nonatomic) id<FaceCaptureHandler> captureHandler;

5. 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.

Objective-C
Swift
1FaceCaptureOptions *options = [[FaceCaptureOptions alloc] initWithLivenessMode:FaceCaptureLivenessModePassive];

6. Create the FaceCaptureHandler instance object using the options and retain the handler by setting it to the earlier prepared property.

Objective-C
Swift
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}];

7. Set the delegate for FaceCaptureHandler.delegate. self has to implement the FaceCaptureHandlerDelegate protocol.

Objective-C
Swift
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}];

8. After FaceCaptureHandler has finished its initialization, the preview view can be set.

Objective-C
Swift
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}];

9. Now it can start capturing.

Objective-C
Swift
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}];

10. 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.

Objective-C
Swift
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.

Objective-C
Swift
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}

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

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

Finger Capture Handler 

Use Cases 

Start Using Finger Capture Handler 

1. Import the framework header to your view controller.

Swift
1#import <BiometricSDK/BiometricSDK.h>

2. 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;

3. Check your license status.

4. 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  }];

5. 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      }];

6. 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    }];

7. 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    }];

8. 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 

Start Using Document Capture Handler 

1. Import the framework header to your view controller.

Swift
1#import <BiometricSDK/BiometricSDK.h>

2. 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;

3. Check your license status.

4. 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      }];

5. 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      }

6. 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  }];

7. 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    }];

8. 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.

Objective-C
Swift
1FaceCaptureOptions *options = [FaceCaptureOptions createFromConfigurationFileWithError:&error];

Bio Match Handler 

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 

List All Templates 

This lists all the templates stored in the database.

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

Glossary of Terms