This is the main entry point that allows you to use the SDK.

Introduction 

The Capture SDK is targeted to developers who want to use the IDEMIA biometric technologies within their mobile apps.

The main features are:

• Biometric captures
• Biometric coding
• Biometric authentication and identification
• Identity documents reading

Please refer to Release Notes to see the list of improvements and fixed issues.

Prerequisites 

Skills Required 

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

• Xcode
• Objective-C/Swift
  • SDK is not supporting Swift 6 language mode.
• iOS (min version is 15.0)
• (optional) cocoapods

Resources Required 

Integration should be performed on a Mac.

The tools required are:

• Xcode that support iOS 15
• iOS device (simulator is not supported)

Licenses Required 

Depending of which declination of the library is used the licenses required are:

• Biometry + Document:

  • MORPHOFACS
  • VERIF
  • IDENT
  • MIMA
  • MSC_CORE
  • MSC_LIVENESS

• Biometry:

  • MORPHOFACS
  • VERIF
  • IDENT
  • MIMA
  • MSC_CORE
  • MSC_LIVENESS

• Document:

  • MIMA
  • MSC_CORE

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

• MSC_DUMP

Sample Project 

The sample project is provided along with this documentation.

Getting Started 

Components 

The SDK is composed of six different components:

• LicenseManager: Object responsible for handling the license.
• FaceCaptureHandler: Handles the capture of the face biometrics through the camera of the device.
• FingerCaptureHandler: Handles the capture of the finger biometrics through the camera of the device.
• BioMatcherHandler: Handles the biometric coding and matching.
• BioStoreDB: Repository to store biometric templates (This component is optional, just in case you don’t want to implement your own database).
• DocumentCaptureHandler: Handles the document reading features (Like reading MRZ documents).
• ImageUtils: Handle the images format conversion, in case the integrator needs to change the image format or import an image.

SDK Variants 

The SDK comes in six different variants.

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

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

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

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

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

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

Analytics 

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

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

Analytics data that we collect include following information:

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

You can disable analytics reporting using the appropriate SDK method.

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

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

You can switch to Wi-Fi only mode with:

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

You can disable analytics as with:

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

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

Project Configuration 

Before using our SDK you need to add Privacy - Camera Usage Description (NSCameraUsageDescriptionkey) to the Info.plist of your application as it will need to use the camera.

Adding the Biometric Capture SDK Framework 

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

• using CocoaPods
• manually

Use CocoaPods (along with cocoapods-artplugin)

If you don't already have the CocoaPods with the Artifactory tool, install it by running the following command:

Bash
1gem install cocoapods-art

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

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

2. Once set, add our repo to your CocoaPod's dependency management system:

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

3. At the top of your project Podfile add:

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

4. 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 (finger+face) features
3
4pod 'BiometricSDK-finger' # Contains only finger features
5
6pod 'BiometricSDK-face' # Contains only face features without internal liveness checking mechanism
7pod 'BiometricSDK-document' # Contains only document features
8pod 'BiometricSDK-face_document' # Contains only face features without internal liveness checking mechanism & documents features

Above configuration installs iOS frameworks. For XCFramework, 'XCFramework' subspec can be used for face, face_document and document variants. Eg.

Ruby
1pod 'BiometricSDK-face_document/XCFramework'

5. Then you can use install:

Bash
1pod install

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

Bash
1pod 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 the Embedded Binaries.

5. Click the Add button (+).

6. Click the Add Other button below the list.

7. Add the following items:

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

Note: XCFrameworks are supported with face, face_document and document variants. XCFrameworks are not yet supported with biometry, biometry_document, fingerprint variants.

SDK Size 

All sizes are estimated download sizes from App Store on arm64 devices. Note that universal IPA file size containing the SDK might be visibly different in case it's built also for other architectures and/or includes bitcode.

Sizes are total sizes for the whole packages which includes:

• an appropriate SDK variant
• capture plugins
• algorithms plugins
• UIExtension library
• UIExtension's additional resources like tutorials and animations

Different packages variants contains:

• offline liveness + matching: an appropriate SDK, Face Normal plugin, F5_4_LOW75 algorithm, UIExtensions, face capturing tutorials
• offline liveness: SDK, Face Normal plugin, F6_0_IDD80 algorithm, UI
• backend: SDK, Face Lite plugin, no algorithm, UI

License Manager 

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

To have a valid license:

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

Before Starting 

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

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

New license manager 

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

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

provideLicenseManager

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

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

Activating license

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

Callback solution:

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

Async solution:

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

LicenseActivationError

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

ActivationErrorType

Document capture - remote (recommended) 

Introduction 

In order to make integration easier and more intuitive - new API has been delivered. It is based on use cases that are self-explaining which provide specific information depending on given use case. This allows to focus on working with data provided by SDK rather than on SDK configuration. What is more, some use cases allows to capture whole document (front and back sides) in single capture session - camera opens only once.

Integration 

Integration with new API is simple and consists of three steps.

1. License activation and camera permission. In order to use SDK proper license has to be activated. Getting started section shows how to handle license and permissions.

2. Add DocumentCaptureView to the layout. This will be not only capture preview but also entry point to the SDK.

Objective-C
Swift
1@property (weak, nonatomic) IBOutlet DocumentCaptureView *captureView;

This view implements DocumentCapture protocol which might be called to manage capture. It contains three methods: configure(with captureUseCase: CaptureUseCase), start(), stop().

Setting up is described below. Methods start and stop are similar to old API's methods to manage capture.

3. Use case creation. In order to start capture, specific use case instance needs to be created. Each use case have sessionInfo property that contains session configuration and delegate that will be used to handle callback methods.

Once these three steps are satisfied, configure method on DocumentCaptureView might be called, passing use case instance as paramerer. Delegate attached to the use case will receive data from the capture.

Use cases 

Capture settings of DocumentCaptureSDK are done by using proper, predefined configuration designed for specific use case. In this way capture configuration is more intuitive and less confusing.

RemoteUseCase

This use case performs document capture with backend communication in order to allow manual verification of the document captured. In order to provide correct flow, RemoteCaptureDelegate, FeedbackDelegate and sessionInfo must be provided during RemoteUseCase initialization. FeedbackDelegate is mandatory to instruct user to properly place device during capture and also when to flip document if both sides are required for verification. RemoteCaptureDelegate informs about whole flow result and provides images of document captured. These images have to be approved in order to proceed with the process. sessionInfo provides information about document capture session on IDEMIA Identity and Verification service for SDK needs to continue the flow.

Swift
1if let useCase = DocumentCaptureUseCase.useCaseForType(self.useCaseType, sessionInfo: sessionInfo, delegate: self) {
2    self.captureView.configure(with: useCase)
3    self.captureView.start()
4}

Delegates 

Delegates available for specific use cases within new API for document capture.

RemoteCaptureDelegate

Delegate dedicated to remote use cases. Two methods needs to be implemented to provide correct flow to the user. Remember that all UI operations should be performed on main thread.

1. The method func captureInfoReceived(images: [CapturedDocumentImage], finalizer: RemoteCaptureFinalizer) is called when a document is captured. It returns a list of images (front, back, or both sides) and a RemoteCaptureFinalizer instance that controls the next steps in the capture flow.

   The RemoteCaptureFinalizer plays a critical role in the remote capture process, offering three key actions:

   • approved(): Approves the captured images and proceeds with sending them to the backend.
   • cancel(): Cancels the entire capture flow, triggering a failure result via the captureDidFinish method.
   • restart(): Restarts the capture flow, reusing the existing session.

   Important: Since methods from RemoteCaptureFinalizer may be invoked at any time, the DocumentCaptureView must remain in memory (i.e., must not be deallocated).

2. func captureDidFinish(remoteResult: RemoteResult) - returns result of remote flow. No other callback will occur after this method. Result might be type of Success or Failure.

Swift
1class DocumentCaptureViewController: UIViewController, RemoteCaptureDelegate {
2    func captureInfoReceived(images: [DocumentImage], finalizer: RemoteCaptureFinalizer) {
3        //Handle captured document
4    }
5
6    func captureDidFinish(remoteResult: RemoteResult) {
7        //remoteResult.isSuccessful ?
8        //true -> Handle success result
9        //false -> Handle error (remoteResult.error)
10    }
11}

FeedbackDelegate

Returns feedback about current capture. Feedback should be displayed to user. Only one function to implement: captureInfoReceived(feedback: FaceCaptureFeedback), where FaceCaptureFeedback is an enum telling about capture condition like: document is too far/too close to camera. Remember that all UI operations should be performed on main thread.

Swift
1class DocumentCaptureViewController: UIViewController, FeedbackDelegate {
2    func captureInfoReceived(feedback: FaceCaptureFeedback) {
3        //Present feedback to the user
4    }
5}

CaptureTimeoutDelegate

The function captureDidTimeout(with images: [CapturedDocumentImage]) returns images that did not meet quality criteria before the capture timed out.

Swift
1func captureDidTimeout(with images: [CapturedDocumentImage]) {
2    // Images captured that did not meet quality criteria before timeout.
3}

Quality Indicators 

DocumentQualityIndicators are returned when document during the capture doesn't meet quality criterias. It is returned on the callback captureDidFinish(remoteResult: RemoteResult) as parameter in the RemoteResult. It is only returned with the callback captureDidTimeout(with images: [CapturedDocumentImage]) in other situation it doesn't happen.

More about quality indicators structure: API reference

Errors 

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

FailureType

DocumentCaptureHandler 

Getting Started with DocumentCaptureHandler 

1. Import the framework header to your view controller.

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

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

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

3. Check your license status here.

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

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

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

6. After DocumentCaptureHandler finishes its initialization, the preview view can be set.

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

Objective-C
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 (e.g. camera) need to be released.

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

DocumentCaptureHandler parameters 

Delegate

This sets the listener to receive the biometric information.

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

Preview

This sets the camera preview.

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

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

Debug Settings

This sets the camera preview.

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

Start Capture

This starts the biometric capture.

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

Stop Capture

This stops the biometric capture.

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

Force Capture

There is possibility to force Biometric Capture SDK to capture a document image. To do so, you need to call the method forceCapture during the capture. The component will bypass the tracking and launch the full resolution capture.

Objective-C
1// Create and save reference to document capture handler
2      //Start capture
3      [self.documentCapture forceCapture];

Switch Camera

This switches between different cameras.

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

Overlay

This sets the overlay option.

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

Orientation

This sets the orientation option.

Objective-C
1[self setOrientation:BIOOrientationPortrait withError:&error];
2        [self setOrientation:BIOOrientationUpSideDown withError:&error];
3        [self setOrientation:BIOOrientationLandscapeLeft withError:&error];
4        [self setOrientation:BIOOrientationLandscapeRight withError:&error];

Options

This retrieves the capture options used in this handler.

Note: Readonly

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

Partial Dump Video

This dumps the last played sequences.

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

Note: To dump a partial video, enable partialDumpVideoRecordEnable before starting a capture. This option should be set in the DocumentCaptureOptions that are used when creating the DocumentCaptureHandler.

Destroy

This releases all the handler resources.

Objective-C
1[handler destroy];

Use Cases 

Read MRZ

This is an example of reading an MRZ document. This use case is intended to be used when the integrator wants to read the MRZ area of a document like on passports, but without retrieving an image of the document.

NOTE: This mode works only for MRZ with 2 or 3 lines. To capture document with 1 line MRZ please use MRZ + Document Image mode described in the next section.

Read MRZ with Document Image

This reads a MRZ document and also captures an image of the document. This use case is intended to be used when the integrator wants to read the MRZ area of a document like on passports, and also retrieve an image of the document.

Capture a Document Image

This captures an image of the document. This use case is intended to be used when the integrator wants to retrieve an image of the document.

Compression Recommendations 

Compression specification:

• Resolution of returned image is 4K.
• Recommended compression is JPEG90.
• Size of image will be around 1.5mb
• The compression is compliant with backend services.

To compress an image of type DocumentImage, it is recommended to use the method from the BIOImage extension: .toJPEG(withQuality:). This ensures proper image compression according to the standards set for backend integration.

Swift
1func documentHandlerCapturedDocumentImage(_ documentImage: DocumentImage) {
2        // Example implementation for compressing DocumentImage using JPEG90 quality
3        let compressedImage = documentImage.toJPEG(withQuality: 0.9)
4        // Now you can use compressedImage as needed, e.g., uploading it to the backend
5    }

DocumentCaptureHandler quality indicator 

If the scanned document does not meet the quality criteria, an error will be returned via the callback captureFinishedWithError(_ error: Error?). To determine the issue, you can retrieve the quality indicators from the userInfo dictionary of the NSError object.

Swift
1func captureFinishedWithError(_ error: Error?) {
2        let nsError = error as NSError?
3        if let indicators = nsError?.userInfo["documentImageQualityIndicators"] as? DocumentQualityIndicators {
4            // operation with the indicators
5        }
6        // here you can do operation with error
7    }

There is more about indicators in the API reference.

ImageUtils 

Objective-C
1- (NSData *)toJPEG;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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