Capture SDK Guide 

The purpose of the Integration Guide is to give developers everything they need to set up and work with a minimally viable application using the Capture SDK.

Introduction 

The Capture SDK (sometimes seen as Morpho Bio SDK in older documentation or code pieces) is targeted to developers who want to use IDEMIA technologies within their mobile apps.

The main features are:

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

Adding the SDK to your project 

Gradle

Configure repository:

XML
1buildscript {
2    repositories {
3        maven {
4          url "$repositoryUrlMI"
5          credentials {
6              username "$artifactoryUserMI"
7              password "$artifactoryPasswordMI"
8          }
9        }
10        ...
11    }
12    ...
13}

repositoryUrlMI: Mobile Identity artifactory repository url

artifactoryUserMI: Mobile Identity artifactory username

artifactoryPasswordMI: Mobile Identity artifactory password

These properties can be obtained through portal and should be stored in local gradle.properties file. In such case credentials will not be included in source code. Configuration of properties:

XML
1artifactoryUserMI=artifactory_user
2artifactoryPasswordMI=artifactory_credentials
3repositoryUrlMI=https://mi-artifactory.otlabs.fr/artifactory/smartsdk-android-local

More about gradle properties can be found here.

For biometric features the dependency is:

Groovy
1implementation ("morpho.mph_bio_sdk.android:SmartBio:version")

For document features the dependency is:

Groovy
1implementation ("morpho.mph_bio_sdk.android:SmartDoc:version")

For all features the dependency is:

Groovy
1implementation ("morpho.mph_bio_sdk.android:SmartSDK:version")

Version: artifact version

Components

The SDK comprises six distinct components:

1. BioCaptureHandler: Handles the capture of the biometrics through the camera of the device.
2. BioMatcherHandler: Handles the biometric coding and matching.
3. DocumentCaptureHandler: Handles the document reading features (like reading MRZ documents).
4. BioStoreDB: Repository to store biometric templates. (This component is optional, in case you don't want to implement your own database.)
5. ImageUtils: Handles the image format conversion, in case the integrator must change the image format or import an image.
6. LicenseManager: Handles the license management. Refer to License Manager for more details.

Access to BioCaptureHandler, BioMatcherHandler and DocumentCaptureHandler is through the Biometric Capture SDK entry points. To learn how to use DocumentCaptureHandler, refer to the DocumentCaptureHandler section for more details.

Design considerations 

• User permissions must be handled by the integrator. You must check that the app permissions are granted by the user if the Android version is higher than 23 (as detailed here).

• Remember: You must always have a valid license before using any method of this SDK. You can activate it through LicenseManager. Refer to License Manager for more details.

• Note: If your app is to run in low memory devices, you must add android:largeHeap="true" to your application.

• If you find that your project requires other native libraries, you must add in your gradle.properties file the following filter:

XML
1android.useDeprecatedNdk=true

And in your build.gradle add filters for the desired ABI. For now, the SDK supports armeabi-v7a and arm64-v8a:

XML
1defaultConfig {
2        ....
3        ndk.abiFilters 'armeabi-v7a','arm64-v8a'
4    }

Prerequisites 

Skills required

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

• Android Studio
• Java for Android
• Android OS

Resources required

Integration may be performed on computers running Windows, Linux, or macOS.

The tools required are:

• Android studio 1 or above
• Android SDK tools: preferred latest version (release 24 or above)
• JDK: preferred latest version (7 or above)
• Android device (emulator is not supported)
• Minimum SDK version is 21

Licenses required

Depending on which implementation 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 video dump feature, you will also need MSC_DUMP.

Licenses are not automatically updated from the server though the apps when licenses are updated on the server side. This responsibility lies with the app when you receive an invalid exception error.

Changes 

• Added passive liveness mode for face capture

Biometric capture SDK structure 

The SDK's structure is displayed below.

Tips 

App size optimization

After adding the SDK to your project you will observe that the size of application has grown significantly. This is because the SDK now includes native libraries for two ABIs: armeabi-v7a and arm64-v8a. What is generated is an .apk file that deploys to Google Play. Your application will contain both application binary interfaces even if one is not used.

Android App Bundle is the solution for this issue. Instead of generating an .apk, it is possible to generate a bundle (.aab). When a user installs the application from the store that contains the bundle, only the required components for the user's specific device will be downloaded.

Additionally, the maximum size of the bundle increases to 150 MB (100 MB is still maximum size for .apk files).

No changes on Google Play are required - just upload .aab instead of .apk. Also, no development in the application project is required.

It is recommended that the bundle options be declared inside the Gradle file, for example:

XML
1android {
2        ...
3    bundle {
4        density {
5            enableSplit true
6        }
7        abi {
8            enableSplit true
9        }
10        language {
11            enableSplit false
12        }
13    }
14}

More about app bundles can be found here.

License manager 

The purpose of this section is to show the API of the license management portion of the SDK, and expose the objects involved.

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 method provides an instance of LicenseManager with a predefined LKMS profile. Operetion with LicenseManager should be executed before starting capture.

Kotlin
1LicenseManager manager = LicenseManager.provideLicenseManager(LkmsProfileId, LkmsApiKey, lkmsUrl)

Activating license

This function 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.

Method handles license management on calling thread.

Callback solution:

Kotlin
1val activationResult = manager.activate(
2        object: LicenseActivationListener {
3            override fun onLicenseActivated() {
4                //License fetched and activated with success.
5            }
6
7            override fun onLicenseActivationFailed(licenseActivationError: LicenseActivationError) {
8                //Failed to fetch or activate the license.
9            }
10        },
11        applicationContext
12    )

Coroutines solution: It returns LicenseActivationResult

Kotlin
1val activationResult = manager.activate(applicationContext)
2    when(activationResult) {
3        is LicenseActivationSuccess -> {
4            //License fetched and activated with success.
5        }
6        is LicenseActivationError -> {
7            //Failed to fetch or activate the license.
8        }
9    }

LicenseActivationResult

This is information of result from activation license using coroutines solution. Instance might be type of:

• LicenseActivationSuccess
• LicenseActivationError

LicenseActivationError

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

ActivationErrorType

Getting started 

This guide illustrates the required steps to configure a minimally viable project for capturing biometrics using the Biometric Capture SDK.

Downloadable sample apps are here:

• Liveness
• Liveness-lite
• Capture fingerprint

Creating your app 

1. Add the SDK library to your app's build.gradle:

Groovy
1implementation ("morpho.mph_bio_sdk.android:SmartBio:version")

If you do not have configured repository for the SDK yet, see introduction that explains how to do that.

2. Add the correct plugin dependency if you use face capture.

Plugins are special extensions to the SDK that might add or change its features. In this way, users can save memory and increase performance by picking plugins they need.

For face capture there are three plugins to choose from. There should be only one plugin selected during the build. If more than one for a specific flavor is selected, it will cause a MultipleFaceInitPluginsException.

Available plugins

• plugin-face-normal should be used when WebBioServer is not used and there is need for strong security during local liveness challenges.

• plugin-face-lite should be used when WebBioServer is used because it can reduce the size of an application significantly.

• plugin-face-cr2dmatching should be used for local usage with additional security feature for FaceLiveness.ACTIVE mode.

Example plugin dependency for face capture:

Groovy
1implementation 'com.idemia.smartsdk:plugin-face-normal:version'

Plugins for face matching 

If you use the finger only variant you can skip this section because the proper plugin is already attached to that version.

For face matching there are three options to choose from. Keep in mind that these algorithms are not compatible.

Stored templates will not be successfully matched against templates from another algorithm.

• plugin-algorithm-f5-4-low75: This has been improved to perform better with default compression. If a previous SDK has been used before and there is a user base with stored templates already, then full migration will be required. All templates must be generated again with the new plugin in use.

• plugin-algorithm-f5-0-vid81: This is the default algorithm that is compatible with previous SDK versions.

• plugin-algorithm-fingerv9: This provides only finger matching.

Remember to attach only one matching plugin per flavor, otherwise a MultipleInitBlockPluginsException will occur.

More about plugins

3. Add the MorphoSurfaceView to the layout where you handle the biometric capture:

XML
1<morpho.urt.msc.mscengine.MorphoSurfaceView
2                        android:id="@+id/morphoSurfaceView"
3                        android:layout_width="match_parent"
4                        android:layout_height="match_parent" />

3. On your activity or fragment get a reference to this view:

Java
1MorphoSurfaceView cameraPreview = (MorphoSurfaceView) findViewById(R.id.morphoSurfaceView);

Note: Do not forget to destroy this when the activity or fragment is destroyed.

Java
1@Override
2                protected void onDestroy() {
3                    // Destroy surface view
4                    if (cameraPreview != null) {
5                        cameraPreview.onDestroy();
6                    }
7                    super.onDestroy();
8                }

4. Activate your license. This can be done in the onCreate(Bundle savedInstanceState) or in a previous stage of your app. This must be done only once.

Java
1LicenseManager manager = LicenseManager.provideLicenseManager(LkmsProfileId, LkmsApiKey, lkmsUrl)
2    val activationResult = manager.activate(applicationContext)
3    when(activationResult) {
4        is LicenseActivationSuccess -> {
5            //License fetched and activated with success.
6        }
7        is LicenseActivationError -> {
8            //Failed to fetch or activate the license.
9        }
10    }

For security reasons it is good to consider storing LKMS credentials outside source code (for example gradle properties).

5. Prepare capture settings. For face capture, you should use FaceCaptureOptions.

Java
1FaceCaptureOptions captureOptions = new   FaceCaptureOptions(FaceLiveness.PASSIVE);
2  captureOptions.setCamera(Camera.FRONT);
3  captureOptions.setCaptureTimeout(120);
4  captureOptions.setOverlay(Overlay.OFF);
5  captureOptions.setTorch(Torch.OFF);

6. In the onResume() method of your activity or fragment, obtain a valid reference to the IBioCaptureHandler using the previously created capture options.

Java
1protected void onResume() {
2           //Create handler
3           BioSdk.createFaceCaptureHandler(this, captureOptions, new MscAsyncCallbacks<IFaceCaptureHandler>() {
4                @Override
5                public void onPreExecute() {
6                  // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
7                }
8                @Override
9                public void onSuccess(IFaceCaptureHandler result) {
10                  // Indicates that initialization succeeded, the returned handler can be used to start the capture.
11                  faceCaptureHandler = result;
12                }
13                @Override
14                public void onError(BioCaptureHandlerError e) {
15                  // An error has occurred during the initialization
16                }
17           });
18          super.onResume();
19       }

7. Add the listeners for the events to the handler:

Java
1faceCaptureHandler.setFaceCaptureResultListener(new FaceCaptureResultListener() {
2          @Override
3          public void onCaptureSuccess(@NotNull FaceImage image) {
4            //Successfully captured image
5          }
6
7          @Override
8          public void onCaptureFailure(@NotNull CaptureError captureError,
9                                     @NotNull IBiometricInfo biometricInfo,
10                                     @NotNull Bundle extraInfo) {
11            //Capture failure
12            );
13          }
14        });
15        faceCaptureHandler.setFaceCaptureFeedbackListener(new FaceCaptureFeedbackListener() {
16            @Override
17            public void onCaptureInfo(FaceCaptureInfo captureInfo) {
18                //Face capture feedback info, like move your face to the right
19            }
20        });
21        faceCaptureHandler.setFaceTrackingListener(new FaceCaptureTrackingListener() {
22            @Override
23            public void onTracking(List<FaceTracking> trackingInfo) {
24                //Tracking info to know where the face is.
25            }
26        });

8. Initialize the preview and capture to start receiving events. It should happen after creating the capture handler. The most common place for this would be onResume:

Java
Kotlin
1       faceCaptureHandler.startPreview(new PreviewStatusListener() {
2      @Override
3      public void onStarted() {
4          try {
5              captureHandler.startCapture();
6          } catch (MSCException e) {
7              // handle exception
8          }
9      }
10
11      @Override
12      public void onError(PreviewError error) {
13          // Preview initialization failed and can not be started
14      }
15   });

9. Destroy the handler when onPause() is invoked:

Java
1@Override
2        protected void onPause() {
3            if(captureHandler!=null) {
4                faceCaptureHandler.stopCapture();
5                faceCaptureHandler.stopPreview();
6                faceCaptureHandler.destroy();
7            }
8            super.onPause();
9        }

10. In your manifest, you must add:

XML
1<!--Declare new permissions-->
2        <permission
3            android:name="your.new.permission.NEW_READ_LKMS_LICENSE_PROVIDER"
4            android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
5        <permission
6            android:name="your.new.permission.NEW_WRITE_LKMS_LICENSE_PROVIDER"
7            android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
8        <permission
9            android:name="your.new.permission.NEW_READ_MPH_BIO_SDK_PROVIDER"
10            android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
11        <permission
12            android:name="your.new.permission.NEW_WRITE_MPH_BIO_SDK_PROVIDER"
13            android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->

XML
1<!--Remove old permissions-->
2        <permission
3            android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider.READ_MPH_BIO_SDK_PROVIDER"
4            tools:node="remove" />
5        <permission
6            android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider.WRITE_MPH_BIO_SDK_PROVIDER"
7            tools:node="remove" />
8        <permission
9            android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider.WRITE_LKMS_LICENSE_PROVIDER"
10            tools:node="remove"
11            />
12        <permission
13            android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider.READ_LKMS_LICENSE_PROVIDER"
14            tools:node="remove"
15            />

XML
1<!--The provider must be defined by the implementing app so as to allow multiple apps-->
2        <!--Bio store provider provider-->
3        <provider
4           android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider"
5           android:authorities="your.new.authority"
6           android:readPermission="your.new.permission.NEW_READ_MPH_BIO_SDK_PROVIDER"
7           android:writePermission="your.new.permission.NEW_WRITE_MPH_BIO_SDK_PROVIDER"
8           tools:replace="android:authorities, android:readPermission, android:writePermission">
9        </provider>

XML
1<!--The provider must be defined by the implementing app so as to allow multiple apps-->
2        <!--Lkms license provider-->
3        <provider
4            android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider"
5            android:authorities="your.new.authority"
6            android:readPermission="your.new.permission.NEW_READ_LKMS_LICENSE_PROVIDER"
7            android:writePermission="your.new.permission.NEW_WRITE_LKMS_LICENSE_PROVIDER"
8            tools:replace="android:authorities, android:readPermission, android:writePermission">
9        </provider>

Analytics 

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

• 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
• Device model and operating system version
• Technical information about performed face, finger, and document capture (such as: capture mode used; 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.

Capture SDK plugins 

Plugins have been introduced to give even more flexibility than variants of the SDK. Every integrator might have different needs and size requirements. A new plugin mechanism allows for greater flexibility. Plugins are split to two groups: feature and algorithm.

Feature plugins 

Provides various SDK functionalities such as: face capture, document capture, and optical character recognition (OCR).

Algorithm plugins 

Provides for extracting biometric data from images, matching this data, and storing it as templates.

How it works 

Capture SDK still has previous variants with predefined plugins in the dependency list that are still required. However, some features might be different, like the matching algorithm or face capture challenge behavior. In such cases, these features might be configured via adding specific plugins.

All that must be done to add a plugin is to put the proper dependency to a project's module that will be using the plugin (How to use them).

Benefits 

The obvious benefit is reducing the number of SDK variants which makes it easier to pick the proper SDK dependency. It also brings flexibility to the product, namely, the ability to mix or replace features in the future or even extend SDK possibilities by implementing your own plugins.

How to use them 

Plugins are just ordinary dependencies. All that must be done is to add the proper dependency for the plugins that are needed. Read carefully about allowed combinations and predefined plugins in SDK variants.

Here is a snippet with all available plugins:

Gradle
1//Feature plugins
2implementation 'com.idemia.smartsdk:plugin-finger:$version'
3implementation 'com.idemia.smartsdk:plugin-face:$version'
4implementation 'com.idemia.smartsdk:plugin-face-normal:$version'
5implementation 'com.idemia.smartsdk:plugin-face-lite:$version'
6implementation 'com.idemia.smartsdk:plugin-face-cr2dmatching:$version'
7implementation 'com.idemia.smartsdk:plugin-face:$version'
8implementation 'com.idemia.smartsdk:plugin-improved-pdf417-detection:$version'
9
10//Algorithm plugins
11implementation 'com.idemia.smartsdk:plugin-algorithm-f5-0-vid81:$version'
12implementation 'com.idemia.smartsdk:plugin-algorithm-f5-4-low75:$version'
13implementation 'com.idemia.smartsdk:plugin-algorithm-f6-0-idd80:$version'
14implementation 'com.idemia.smartsdk:plugin-algorithm-fingerv9:$version'

Allowed combinations 

Here are all possible combinations of plugins for specific use cases.

As mentioned above, the SDK variants have predefined plugins dependency, so that only a few must be defined.

See what predefined plugins has which variant of the SDK you use.

Warning: Only one of: plugin-face-lite, plugin-face-normal, plugin-face-cr2dmatching can be used at a time. The integrator must pick one of them. A MultipleFaceInitPluginsException will occur if more than one has been picked.

SDK variants and their plugins 

Each SDK plugin variant delivers something different - check carefully what each plugin variant contains. Plugin variants should not be added in a module that uses this specific variant. As can be seen below, no document-related plugins must be added for variants that deliver this feature. In other words, variants contain all plugins that are required and have no alternatives.

Plugins that might be added for a Capture SDK variant:

• One of: plugin-face-normal, plugin-face-lite, plugin-face-cr2dmatching
• One of: plugin-algorithm-f5-4-low75, plugin-algorithm-f5-0-vid81, plugin-algorithm-f6-0-idd80, plugin-algorithm-fingerv9 (this one is not recommended if face matching will be performed)

Plugins that can be added for the Biometric Capture SDK variant:

• One of: plugin-face-normal, plugin-face-lite, plugin-face-cr2dmatching
• One of: plugin-algorithm-f5-4-low75, plugin-algorithm-f5-0-vid81, plugin-algorithm-f6-0-idd80, plugin-algorithm-fingerv9 (this one is not recommended if face matching is going to be performed)

There are no plugins for the SmartFinger variant.

Plugins that can be added for the SmartFace variant:

• One of: plugin-face-normal, plugin-face-lite, plugin-face-cr2dmatching
• One of: plugin-algorithm-f5-4-low75, plugin-algorithm-f5-0-vid81, plugin-algorithm-f6-0-idd80

Plugins that can be added for the SmartFaceDoc variant:

• One of: plugin-algorithm-f5-4-low75, plugin-algorithm-f5-0-vid81, plugin-algorithm-f6-0-idd80

However, this variant is meant to be used with WebBioServer which performs matching operations (no need to do that locally).

For SDK variants with document plugin-improved-pdf417-detection may be added in order to improve capture of barcodes.

Feature plugins descriptions 

plugin-face

Basic plugin needed for face capture. Usually it is predefined in every SDK variant that delivers face capture functionality.

plugin-face-normal

Should be used for face capture when WebBioServer is not used and there is a need for strong security during local liveness challenges.

plugin-face-lite

Should be used when WebBioServer is used for liveness check during face capture, because it can reduce the size of application significantly.

plugin-face-cr2dmatching

Should be used for local usage (without WebBioServer) when additional security feature for FaceLiveness.ACTIVE mode is needed.

plugin-finger

Plugin needed for finger capture. Usually it is predefined in every SDK variant that delivers finger capture functionality.

plugin-improved-pdf417-detection

Plugin that can be used to speed up barcode capture.

Algorithm plugins descriptions 

plugin-algorithm-f6-0-idd80

Recommended algorithm for face capture. It is more accurate than f5-4-low75 and much smaller than f5-0-vid81.

plugin-algorithm-f5-4-low75

Improved to perform better with default compression. If a previous SDK has been used before and there is a user base with stored templates already, then full migration of the user's biometrics will be required. All templates must be generated again with the new plugin in use.

plugin-algorithm-f5-0-vid81

This is the default algorithm that is compatible with previous SDK versions.

plugin-algorithm-fingerv9

Provides only finger matching feature. It is best to pick this one when only finger matching will be performed.

WARNING

The algorithms are NOT compatible with each other. The templates generated by one of the algorithms cannot be processed with the other one; that is, it is not possible to match a template generated with F6_0_IDD80 against a template generated with F5_4_LOW75 or F5_0_VID81. If an integrator wants to change the algorithm in their solution, all the stored templates must be recreated with the new algorithm.

SDK size 

This is the estimated size of an SDK variant with all its dependencies, like predefined plugins (see Plugins section). The UI-extension is not included in size as it is not a predefined dependency.

Plugins size 

Integration guide 

The purpose of this document is to show the API of the SDK and expose all of its involved objects.

Use cases 

Capture biometrics

Below is the generic execution flow to perform a biometric capture (Get Picture), and get information about the biometry. For example, getting a picture and moving your head to the left.

Capture timeout

Below is the generic execution flow to be followed when a capture timeout occurs.

Capture enroll

Below is the generic execution flow to perform a biometric capture (Get Picture). After that, the biometrics template is extracted from the image returned by the capture component. The biometric template is linked to one user using the userUUID. The UUID of this template and the userUUID are stored in a database.

Capture authenticate

Below is the generic execution flow to perform a biometric capture (Get Picture). The biometrics template is then extracted from the image and returned by the capture component. These are the candidate templates that you must use to create an IBiometricCandidate.

After the IBiometricCandidate is created, a list of reference templates must be extracted. These will then be used to create an IBiometricReference object with which to match against the IBiometricCandidate and authenticate that the candidate templates belong to the user.

There are two ways to extract a list of template references: the first is to retrieve them from the database used during the enrollment process; the second is to extract the templates from another image with detectBiometrics(...).

Capture identify

Below is the generic execution flow to perform a biometric capture (Get Picture). The biometrics template is then extracted from the image and returned by the capture component. These are the candidate templates which you must use to create an IBiometricCandidate.

After the IBiometricCandidate is created, a list of reference templates must be extracted. These will then be used to create an IBiometricReference object with which to match against the IBiometricCandidate and authenticate that the candidate templates belong to the user.

Creating BioMatcherHandler

Below is the generic execution flow to retrieve and release a BioMatcherhandler.

Authenticating

Below is the generic execution flow to perform a generic verification process which involves extracting the biometrics template from an image. These are the candidate templates which you must use to create an IBiometricCandidate.

After the IBiometricCandidate is created, a list of reference templates must be extracted. These will then be used to create an IBiometricReference object with which to match against the IBiometricCandidate and authenticate that the candidate templates belong to the user.

There are two ways to extract a list of template references: the first is to retrieve them from the database used during the enrollment process; the second to is extract the templates from another image with detectBiometrics(...).

Identifying

Below is the generic execution flow to perform a generic identification process which involves extracting the biometrics template from an image. These are the candidate templates which you must use to create an IBiometricCandidate.

After the IBiometricCandidate is created, a list of reference templates must be extracted. These will then be used to create an IBiometricReference object with which to match against the IBiometricCandidate and authenticate that the candidate templates belong to the user.

Detect biometrics

This describes detecting the biometrics in an IImage. This function is intended to be used to extract all the biometric templates contained in an image; for example, all the faces that are in an image.

Create capture options from configuration file

The integrator can load options from a configuration file to create capture handlers. Such a file contains predefined settings delivered by the CaptureSDK team that can not be changed. Configuration contains a signature and any change to file will cause the exception, SignatureVerificationException, during its loading by the SDK. The configuration file should be located in the assets directory. Every ICaptureOptions instance (that is, FaceCaptureOptions, FingerCaptureOptions, and DocumentCaptureOptions) has a static method, createFromConfigurationFile, that provides the options of its instance, if that file contains it. Otherwise a FeatureConfigurationMissingException will be thrown.

Finger capture 

OverviewRough idea when that may be? 

Finger ridges have tiny minutiae that makes them difficult to alter. They are unique to each individual and durable over a lifetime. The probability of two people having the same fingerprints is approximately 1 in 64,000,000,000. This makes finger ridges the ideal long-term markers for human identity.

The Capture SDK applies this characteristic for easy authentication and identification using any modern Android or iOS smartphone equipped with a standard camera. Capture SDK is a software library used for scanning fingerprints.

Capture SDK features

• Fingerprint acquisition results in raw images of finger ridges.

  Note: The conversion into worldwide WSQ1 format with a built-in converter is possible.

• Biometric data extraction.

• Biometric data storage.

• Biometric data comparison to authenticate (1:1) or identify (1

  )

  Note: Once the biometric data is extracted, you can utilize the fast authentication mode. This reduces the process to encompass fingerprint acquisition and authentication only.

Dependencies

Implement a dependence with either a predefined or custom configuration:

Predefined:

XML
1implementatation "morpho.mph_bio_sdk.android:SmartFinger:$smartSdkVersion"

Custom:

XML
1implementation "morpho.mph_bio_sdk.android:SmartSDK:$smartSdkVersion"
2 implementation "com.idemia.smartsdk:plugin-algorithm-fingerv9:$smartSdkVersion"

More details about plugin dependencies can be found here

Description

There are four main components that can be used together or separately, depending on the use case: FingerCaptureHandler, BioMatcherHandler, ImageUtils, BioStoreDB.

FingerCaptureHandler is an extension of BioCaptureHandler which is a part of Biometric Capture SDK. It can capture, check liveness, and authenticate an user's fingerprints.

There are three available modes:

• FINGERS, THUMB - captures fingerprint images (fingers or thumb, respectively) and optionally checks liveness.

• AUTHENTICATION - captures fingerprint images, checks liveness, and determines whether the captured data matches with the chosen template.

BioMatcherHandler extracts templates with biometric data from images and also compare them. As a result of the comparison, score is returned. The score value determines if both templates belong to the same user or not. Read more about BioMatcherHandler

ImageUtils uses various conversion types; read section about ImageUtils.

BioStoreDB persists the templates when implemented by the integrator. Use of this component is optional. More about BioStoreDB

Summary

1. To create a FingerCaptureHandler instance you must declare the FingerCaptureOptions.

   Regardless of the capture mode, set the basic configuration:

   • specify capture mode
   • whether a UI overlay be visible during capture
   • which of smartphone's cameras should be used to perform capture
   • what level of liveness check should be performed
   • declare timeout to define capture's duration

   When you choose FINGERS mode you can set which fingers are missing to capture. Default is zero amputated fingers. When you choose THUMB you can only scan a thumb.

2. When the FingerCaptureOptions configuration completes, create FingerCaptureHandler.

3. Register the listener with result callbacks.

4. To perform a capture, start the camera preview and then start the capture.

5. After the time declared in the FingerCaptureOptions passes, the result callback is returned.

For code examples, recommended configuration, and more detailed description, check the page dedicated to a specific capture option.

Fast authentication 

Fast Authentication is a special mode to authenticate fingerprints right after capture. There is one mode that can be used:

• AUTHENTICATION for fingers

To use this mode you should have a list of MorphoTemplate templates from fingerprints that have been saved from previous captures during enrollment. These templates will be used to compare with current fingerprints from the current captures.

This mode returns IAuthenticationResult.

Flow

1. Create LicenseMangager.
2. Retrieve the license.
3. Activate the license.
4. Get a list of templates from MorphoTemplate.
5. Create a BiometricReference.
6. Create the FingerCaptionOptions with added BiometricReference and threshold.
7. Create the FingerCaptureHandler.
8. Set the listener, setAuthenticationListener.
9. Start the capture.
10. On callback, process the result.
11. Stop the capture.

Below is the sequence diagram of that flow.

Creating fast authentication use case

1. Create a biometric reference.

Get the user instance form BioStoreDB and choose MorphoTemplate for the finger. From the BioStoreDB get the list of MorphoTemplate templates and create IBiometricReference.

Kotlin
1BioStoreDB.listUsers(
2    this@FingerCameraActivity,
3    object : DataBaseAsyncCallbacks<List<IUser>> {
4        override fun onPreExecute() {}
5        override fun onSuccess(iUsers: List<IUser>) {
6            if (iUsers.isNotEmpty()) {
7                val user = iUsers[0]
8                BioStoreDB.listTemplates(
9                    this@FingerCameraActivity,
10                    user.uuid,
11                    BiometricModality.FRICTION_RIDGE,
12                    object : DataBaseAsyncCallbacks<List<IMorphoTemplate>> {
13                        override fun onPreExecute() {}
14
15                        override fun onSuccess(references: List<IMorphoTemplate>) {
16                            ...
17                            //reference candidates
18                            val reference = BiometricReference(user.uuid, BiometricModality.FRICTION_RIDGE)
19                            reference.addTemplates(references)
20                            ...
21                        }
22
23                        override fun onError(e: Exception) {}
24                    })
25                }
26            }
27
28    override fun onError(e: Exception) {}
29})

2. Add to FingerCaptureOptions the IBiometricReference with a threshold and create the FingerCaptureHandler.

Create FingerCaptureOptions with the added threshold and biometricRefernece. Then create FingerCaptureHandler.

Kotlin
1val fingerCaptureOptions = FingerCaptureOptions(BioCaptureMode.FINGERS, Hand.RIGHT)
2captureOptions.liveness = FingerLiveness.LOW
3captureOptions.bioCaptureMode = BioCaptureMode.FINGERS
4captureOptions.camera = Camera.REAR
5captureOptions.overlay = Overlay.ON
6captureOptions.captureTimeout = 10
7fingerCaptureOptions.biometricReference = reference
8fingerCaptureOptions.threshold = 3000
9fingerCaptureOptions.uhdResolutionEnabled = true
10createFingerCaptureHandler(fingerCaptureOptions)
11
12BioSdk.createFingerCaptureHandler(this, captureOptions, object : MscAsyncCallbacks<IFingerCaptureHandler> {
13    override fun onPreExecute() {}
14    override fun onSuccess(result: IFingerCaptureHandler) {
15        onFingerCaptureInitialized(result)
16    }
17
18    override fun onError(e: BioCaptureHandlerError) {}
19})

3. Add the listener to the FingerCaptureHandler responsible for the fast authentication result.

To create a FingerCaptureHandler, add the callback responsible for Fast Authentication. In this callback, process the result. The next step will vary based on individual business workflows.

Kotlin
1fingerCaptureHandler.setAuthenthicationListener{ authenticationResult ->
2    if(authenticationResult.status == AuthenticationStatus.SUCCESS){
3        onAuthenticationSuccess(authenticationResult)
4    } else {
5        onAuthenticationFailure(authenticationResult)
6    }
7};

Results

IAuthenticationResult

This is the interface that represents an authentication result.

AuthenticationStatus

This is the enum class that represents whether the authentication is successful or not.

The authentication is successful when the score is greater than the threshold.

Capture errors 

Errors returned when finger capture fails.

BioStore 

With the BioStore component you can save biometric templates in a device's memory. Usage of this component is optional, depending on the integrator's needs.

BioStore allows operations for a specific user like: listing templates, adding new templated, updating templates, removing templates.

A more detailed description about BioStore can be found here

Usage

The most common use case for BioStore is to save a template and restore it later to do matching against a new capture. To do this, there must be at least one user added.

Add new user

Java
Kotlin
1IUser user = new User();
2user.setName("Name");
3BioStoreDB.addUser(context, user, new DataBaseAsyncCallbacks<UUID>() {
4    @Override
5    public void onPreExecute() {
6        // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
7    }
8
9    @Override
10    public void onSuccess(UUID result) {
11        //User saved
12    }
13
14    @Override
15    public void onError(Exception e) {
16        // An error has occurred
17    }
18});

Listing saved templates for the finger

This lists the templates stored in the repository and filters them by user and BiometricModality.

Java
Kotlin
1BioStoreDB.listTemplates(context, userId, BiometricModality.FRICTION_RIDGE, new DataBaseAsyncCallbacks<List<IMorphoTemplate>>() {
2        @Override
3        public void onPreExecute() {
4            // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
5        }
6
7        @Override
8        public void onSuccess(List<IMorphoTemplate> result) {
9            //The list of templates that match the criteria
10        }
11
12        @Override
13        public void onError(Exception e) {
14            // An error has occurred
15        }
16});

Save templates for the finger

Store a template in the repository. If there is a previous template with the same user UUID, the biometric location and biometric modality will be updated and their UUID returned.

Note: There cannot be two templates with the same configuration.

Java
Kotlin
1BioStoreDB.addTemplate(context, morphoTemplate, new DataBaseAsyncCallbacks<UUID>() {
2        @Override
3        public void onPreExecute() {
4             // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
5        }
6
7        @Override
8        public void onSuccess(UUID result) {
9            //The template has been added, and template's uuid is returned as a parameter
10        }
11
12        @Override
13        public void onError(Exception e) {
14            // An error has occurred
15        }
16});

Finger matching 

The Capture SDKs can match biometric templates with the same biometric modality to get the IAuthenticationResult, which is based on a similarity score.

An example of such a comparison follows.

Matching flow

BioMatcherHandler creation

Java
Kotlin
1IBioMatcherHandler matcherHandler = null;
2IBioMatcherSettings bioMatcherSettings = new BioMatcherSettings();
3    //To configure finger print template format
4    bioMatcherSettings.setFingerprintTemplate(MorphoFingerTemplateFormat.PKCOMPV2);
5    BioSdk.createBioMatcherHandler(this, bioMatcherSettings, new BioMatcherAsyncCallbacks<IBioMatcherHandler>() {
6            @Override
7            public void onPreExecute() {
8                // Optional hook on the builtin Android AsyncTask call-back `onPreExecute`
9            }
10
11            @Override
12            public void onSuccess(IBioMatcherHandler result) {
13                // Indicates that initialization succeeded, the returned handler can be used to perform the matching and identify operations.
14                matcherHandler = result;
15            }
16
17            @Override
18            public void onError(Exception e) {
19                // An error has occurred
20            }
21        });

Authentication

Requirements

• Create a BioMatcherHandler. More about MatcherHandler.

• Obtain candidate fingerprints' templates. In most use cases they are acquired during the enrollment process.

• Obtain reference templates for matching. It is possible to match templates stored in a database or other persistence solution, but in most cases a reference is acquired from a previous finger capture during the authentication process.

• Before matching, authentication options must be created. Such options contain the threshold that must be exceeded by the matching score to have a successful authentication.

• Once those items are complete, the biometric candidate can be matched against the reference. As a result the IAuthenticationResult object will be returned. It has two fields: status - indicating if the authentication is successful or not and score which might be in the range 0 – 50000.

Java
Kotlin
1//Authentication options
2IAuthenticationOptions authenticationOptions = new AuthenticationOptions();
3authenticationOptions.setThreshold(3500);
4
5//Biometric candidate
6IBiometricCandidate biometricCandidate = new BiometricCandidate(BiometricModality.FRICTION_RIDGE);
7//We add all the templates for this candidate
8biometricCandidate.addTemplates(candidates);
9
10//Biometric references
11IBiometricReference biometricReference = new BiometricReference(user.getUuid(), BiometricModality.FRICTION_RIDGE);
12//We add all the templates for this user
13biometricReference.addTemplates(references);
14
15matcherHandler.authenticate(authenticationOptions, biometricCandidate, biometricReference, new BioMatcherAsyncCallbacks<IAuthenticationResult>() {
16    @Override
17    public void onPreExecute() {
18        // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
19    }
20
21    @Override
22    public void onSuccess(IAuthenticationResult result) {
23        //The result of the authentication
24        long resultScore = result.getScore();
25        //authentication status (FAILURE, SUCCESS...)
26        AuthenticationStatus authenticationStatus = authenticationResult.getStatus();
27    }
28
29    @Override
30    public void onError(Exception e) {
31        // An error has occurred
32    }
33});

Parameters

Passive capture 

Passive capture captures fingerprints without any challenges performed by the user.

There are two BioCaptureMode values available for finger capture:

• FINGERS for scans of 1 to 4 fingers.
• THUMB` for scans of one finger

Parameters

Capture flow

Sequence diagram

1. After the activation of license, create the handler with the necessary defined capture options.

2. Register the listener to get the result callbacks.

3. When it finishes, use the handler to start the camera preview and capture respectively.

Note: After the capture is finished, remember to stop the preview and the capture. When you finish, destroy the capture.

Note that diagram represents abstract BioCapture flow. FingerCapture differs with its capture result listener. More information is in listeners.

• The capture starts just after the camera preview is started.

• The capture lasts as long as the timeout duration previously set.

The user must fit and stabilize their fingers inside a preview screen during the capture process. It is recommended to turn on the overlay in the capture settings that displays an intuitive UI.

Capture screen with overlay

Capture options configuration

Kotlin
1val options = FingerCaptureOptions()
2      options.bioCaptureMode = BioCaptureMode.FINGERS
3      options.overlay = Overlay.ON
4      options.camera = Camera.REAR
5      options.captureTimeout = 10
6      options.liveness = FingerLiveness.MEDIUM

The smartphone's camera is on by default as it is recommended for better capture performance. However, it can be turned off if needed.

Listeners

FingerCaptureResultListener has two methods: onCaptureSuccess and onCaptureFailure. These return result data on a successful capture and a capture error on a capture with errors.

Kotlin
1val handler = BioSdk.createFingerCaptureHandler(context, options)
2   handler.setFingerCaptureResultListener(object : FingerCaptureResultListener {
3       override fun onCaptureFailure(
4           captureError: CaptureError,
5           biometricInfo: IBiometricInfo,
6           extraInfo: Bundle
7       ) {
8           // handle capture failure
9       }
10
11       override fun onCaptureSuccess(
12           images: MutableList<MorphoImage>,
13           captureResult: FingerCaptureResult
14       ) {
15          // handle capture success
16       }
17   }

Result

On a successful capture:

• A list of five images of the type MorphoImage is returned, where one image contains all of the fingers and four gray-scale fingerprint images that represents separate fingers compressed with a WSQ algorithm.

• FingerCaptureResult, where its data should be considered only if FingerLiveness has a value other than FingerLiveness.NONE. It consists of a score value that represents the confidence of liveness recognition and the FingerLivenessResult that holds the decision on whether the captured fingers belongs to a real person or not.

Document capture 

Getting started 

The guide illustrates the necessary steps to configure and use a minimally viable project to read documents using the Biometric Capture SDK.

Downloadable sample apps are at Document autocapture.

To create your own app:

1. Add the SDK library to your app's build.gradle:

Java
1implementation ("morpho.mph_bio_sdk.android:SmartDoc:version")

2. Add the MorphoSurfaceView to the layout where you handle the biometric capture.

XML
1<morpho.urt.msc.mscengine.MorphoSurfaceView
2                        android:id="@+id/morphoSurfaceView"
3                        android:layout_width="match_parent"
4                        android:layout_height="match_parent" />

3. On your activity or fragment, get a reference to this view:

Java
1MorphoSurfaceView cameraPreview = (MorphoSurfaceView) findViewById(R.id.morphoSurfaceView);

Note: Do not forget to destroy the reference when the activity or fragment is destroyed.

Java
1@Override
2                protected void onDestroy() {
3                    // Destroy surface view
4                    if (cameraPreview != null) {
5                        cameraPreview.onDestroy();
6                    }
7                    super.onDestroy();
8                }

4. Activate your license. You can do that in the onCreate(Bundle savedInstanceState), or in a previous stage of your app.

Kotlin
1LicenseManager manager = LicenseManager.provideLicenseManager(LkmsProfileId, LkmsApiKey, lkmsUrl)
2    val activationResult = manager.activate(applicationContext)
3    when(activationResult) {
4        is LicenseActivationSuccess -> {
5            //License fetched and activated with success.
6        }
7        is LicenseActivationError -> {
8            //Failed to fetch or activate the license.
9        }
10    }

5. In the onResume() method of your activity or fragment, you must obtain a valid reference of the IDocumentCaptureHandler.

Java
1protected void onResume() {
2           //Sample configuration
3           //The activate process was OK.
4           // Populate a CaptureOptions object
5           IDocumentCaptureOptions captureOptions = new DocumentCaptureOptions(
6                new DocumentCaptureModeConfiguration {
7                    public DocumentMode provideCaptureMode() {
8                        return DocumentMode.READ_MRZ
9                    }           
10           });
11           captureOptions.setDocumentCaptureMode();
12           captureOptions.setCamera(Camera.REAR);
13           captureOptions.setTorch(Torch.OFF);
14           captureOptions.setOverlay(Overlay.ON);
15           captureOptions.setCaptureTimeout(120);
16           BioSdk.createDocumentCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IDocumentCaptureHandler>() {
17               @Override
18               public void onPreExecute() {
19                   // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
20               }
21               @Override
22               public void onSuccess(IDocumentCaptureHandler result) {
23                   // Indicates that initialization succeeded, the returned handler can be used to start the capture.
24               }
25               @Override
26               public void onError(BioCaptureHandlerError e) {
27                   // An error has occurred during the initialization
28               }
29           });
30          super.onResume();
31       }

6. Add the listeners for the events to the handler.

Java
1//MRZ callbacks
2captureHandler.setDocumentCaptureListener(new DocumentCaptureListener() {
3    @Override
4    public void onCaptureImageDocument(DocumentImage image) {
5        //If rectification is enabled we will receive several callbacks to this method (One per image, DATA_PAGE, PORTRAIT…)
6        //Document image captured
7        try {
8            byte[] jpegImage = image.getJPEGImage(); Bitmap documentImage = BitmapFactory.decodeByteArray(jpegImage, 0, jpegImage.length);
9            //show the document image
10        }
11        catch (Exception e){
12            Log.e(TAG, "", e);
13        }
14        //If rectification is disabled and we want to get all the images encoded into the location coordinates of the image
15        List<DocumentImage> croppedImages = ImageUtils.extractImages(image);
16    }
17    @Override
18    public void onCaptureFieldImageDocument(DocumentImage image, String labelName) {
19        //A field has been coded
20    }
21    @Override
22    public void onMRZDocumentRead(List<IMRZLine> mrzLines, IMrzRecord mrzRecord) {
23        //MRZ captured
24    }
25    @Override
26    public void onDocumentCaptureFailure(DocumentCaptureError captureError, DocumentImageQualityIndicators indicators) {
27        //Capture failed
28    }
29    @Override
30    public void onCaptureFinish() {
31        //Capture finished
32    }
33});
34//Barcode callbacks
35captureHandler.setBarcodeListener(new BarcodeListener() {
36    @Override
37    public void onBarcodeRead(List<String> capture) {
38        //Barcode captured
39    }
40    @Override
41    public void onDocumentCaptureFailure(DocumentCaptureError captureError, DocumentImageQualityIndicators indicators) {
42        //Capture failed
43    }
44    @Override
45    public void onCaptureFinish() {
46        //Capture finished
47    }
48});
49//Capture feedback listener
50captureHandler.setDocCaptureFeedbackListener(new DocumentCaptureFeedbackListener() {
51    @Override
52    public void onCaptureInfo(DocCaptureInfo docCaptureInfo) {
53        //Document captures info
54    }
55});
56//Tracking listener
57captureHandler.setDocumentTrackingListener(new DocumentCaptureTrackingListener() {
58    @Override
59    public void onTracking(List<MorphoDocumentRegion> trackingInfo) {
60        //Tracking info
61    }
62});

7. Initialize the preview and capture to start the receive events.

Java
Kotlin
1  captureHandler.startPreview(new PreviewStatusListener() {
2       @Override
3       public void onStarted() {
4           try {
5               captureHandler.startCapture();
6           } catch (MSCException e) {
7               // handle exception
8           }
9       }
10
11       @Override
12       public void onError(PreviewError error) {
13           // Preview initialization failed and can not be started
14       }
15   });

8. Destroy the handler when onPause() is invoked.

Java
1@Override
2        protected void onPause() {
3            if(captureHandler!=null) {
4                captureHandler.destroy();
5            }
6            super.onPause();
7        }

9. If you must force a document capture:

Java
1if(captureHandler!=null){
2    //Force a document capture
3    captureHandler.forceCapture();
4}

10. In your manifest you must add:

XML
1<!--Declare new permissions-->
2    <permission
3        android:name="your.new.permission.NEW_READ_LKMS_LICENSE_PROVIDER"
4        android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
5    <permission
6        android:name="your.new.permission.NEW_WRITE_LKMS_LICENSE_PROVIDER"
7        android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
8    <permission
9        android:name="your.new.permission.NEW_READ_MPH_BIO_SDK_PROVIDER"
10        android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->
11    <permission
12        android:name="your.new.permission.NEW_WRITE_MPH_BIO_SDK_PROVIDER"
13        android:protectionLevel="signature" /> <!--unless otherwise required, set the maximum security permission -->

XML
1<!--Remove old permissions-->
2    <permission
3        android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider.READ_MPH_BIO_SDK_PROVIDER"
4        tools:node="remove" />
5    <permission
6        android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider.WRITE_MPH_BIO_SDK_PROVIDER"
7        tools:node="remove" />
8    <permission
9        android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider.WRITE_LKMS_LICENSE_PROVIDER"
10        tools:node="remove"
11        />
12    <permission
13        android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider.READ_LKMS_LICENSE_PROVIDER"
14        tools:node="remove"
15        />

XML
1<!--The provider must be defined by the implementing app so as to allow multiple apps-->
2<!--Bio store provider provider-->
3<provider
4   android:name="com.morpho.mph_bio_sdk.android.sdk.content_provider.BioStoreProvider"
5   android:authorities="your.new.authority"
6   android:readPermission="your.new.permission.NEW_READ_MPH_BIO_SDK_PROVIDER"
7   android:writePermission="your.new.permission.NEW_WRITE_MPH_BIO_SDK_PROVIDER"
8   tools:replace="android:authorities, android:readPermission, android:writePermission">
9</provider>

XML
1<!--The provider must be defined by the implementing app so as to allow multiple apps-->
2<!--Lkms license provider-->
3<provider
4    android:name="com.morpho.lkms.android.sdk.lkms_core.content_provider.LkmsStoreProvider"
5    android:authorities="your.new.authority"
6    android:readPermission="your.new.permission.NEW_READ_LKMS_LICENSE_PROVIDER"
7    android:writePermission="your.new.permission.NEW_WRITE_LKMS_LICENSE_PROVIDER"
8    tools:replace="android:authorities, android:readPermission, android:writePermission">
9</provider>

11. You must also set to landscape the orientation of the activity that will read MRZ:

XML
1<activity android:name="YOUR_ACTIVITY_NAME"
2            android:screenOrientation="landscape">
3</activity>

Integration guide 

The purpose of this section is to show the API of the SDK and expose its objects.

Use cases

In order to get informations from capture, proper listeners have to be applied to DocumentCaptureHandler.

All use cases can retrieve data from:

• DocumentCaptureFeedbackListener - provides information about capture conditions like: glare, too far/close to document etc.
• DocumentCaptureTrackingListener - provides document coordinates on preview (coordinates are relative to preview frame size - not display size).

Read MRZ

This use case is used when the integrator wants to read the MRZ area of a document, such as those found on passports, but without retrieving the document. In such case listener: DocumentCaptureListener should be applied as it provides MRZ value read during capture.

Read MRZ with document image

This use case is used when the integrator wants to read the MRZ area of a document, such as those found on passports. It also retrieves an image of the document.

In such case listener: DocumentCaptureListener should be applied as it provides MRZ value read during capture and document image itself.

Capture a document image

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

In such case listener: DocumentCaptureListener should be applied as it provides document image that has been captured. If capture did not finish successfully before timeout, it returns best frame from acquisition attempt.

Read a QR code

This use case is used when the integrator wants to read a QR Code.

To get QR code or PDF417 data use listeners:

• BarcodeListener - to get data as String
• BarcodeRawDataListener - to get data as ByteArray

New document API 

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. More about use cases can be found here.

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.

XML
1<com.idemia.capture.document.api.DocumentCaptureView
2      android:id="@+id/captureView"
3      android:layout_width="match_parent"
4      android:layout_height="match_parent" />

This view implements interface DocumentCapture which might be called to manage capture. It contains four methods: setUp(useCase: CaptureUseCase, lifecycle: Lifecycle), start(), stop(), destroy() .

Setting up is described below. Methods start, stop and destroy are similar to old API's methods to manage capture. However if Lifecycle instance has been passed during setup - there is no need to use these three methods - starting, stoping and destroying will be handled automatically.

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 set of listeners that might be applied in order to receive data from capture.

Once these three steps are satisfied, setUp method on CaptiveView might be called, passing use case instance as paramerer. If Lifecycle instance is also passed - there is no need to handle lifecycle methods of CaptureView (start/stop/destroy). Listeners attached to use case that has been previously created will provide data from 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. Every use case take parameters only for this exact use case needs. In most cases it will be timeout value and listeners for capture feedback/result.

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, FeedbackListener, RemoteListener and SessionInfo must be provided during RemoteUseCase initialization. FeedbackListener is mandatory to instruct user to properly place device during capture and also when to flip document if both sides are required for verification. RemoteListener informs about whole flow result and provides images of document captured. These images have to be approved in order to proceed with the process more detailed description might be found in listeners section. SessionInfo provides information about document capture session on IDEMIA Identity and Verification service for SDK needs to continue the flow.

It also contains field feedbackSamplingTime which can be used to define time between showing feedbacks for the capture.

Kotlin
1captureView.setUp(
2    RemoteUseCase(
3    feedbackListener,
4    adjudicationListener,
5    sessionInfo
6    ),
7    lifecycle
8)

Listeners 

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

RemoteListener

Listener 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. onDocumentCaptured(images: List<DocumentImage>, captureFinalizer: CaptureFinalizer) - this method is being called when document has been captured. List of images (front, back or both sides images) is returned. CaptureFinalizer instance allows to retry capture, cancel whole flow (Failure instance of Result will be returned on onResult method) or approve images which continues remote flow. Notice that CaptureFinalizer can retry capture which means that whole remote flow (including displaying captured document) must be performed on the same Activity where DocumentCaptureView is attached.

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

Kotlin
1private val remoteListener = object : RemoteListener {
2    override fun onDocumentCaptured(
3        images: List<DocumentImage>,
4        captureFinalizer: CaptureFinalizer
5    ) {
6        //Handle captured document
7    }
8
9    override fun onResult(result: Result) {
10        when (result) {
11            is Failure -> //Handle failure result
12            is Success -> //Handle success result
13        }
14    }
15}

FeedbackListener

Returns feedback about current capture. Feedback should be displayed to user. Only one function to implement: onFeedback(feedback: CaptureFeedback), where CaptureFeedback 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.

Kotlin
1private val feedbackListener = object : FeedbackListener {
2    override fun onFeedback(feedback: CaptureFeedback) {
3        //Present feedback to the user
4    }
5}

Time between feedbacks is defined (in seconds) by feedbackSamplingTime property of CaptureUseCase. By default it is 2 seconds.

Errors 

For every flow there is possibility to receive Failure type from method onCaptureFinish in CaptureStateListener. It means that something went wrong during the capture or backend communication. Fortunately, Error object contains a lot of useful informations that help to handle failed flow.

Failure

FailureType

DocumentImageQualityIndicators

This object contains failure reasons of the capture.

Biocapture SDK 

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

Note: You must always have a valid license before using any method of this SDK.

getInfo

This method allows the integrator to retrieve information about the SDK.

An example snippet is shown:

Java
1IBioSdkInfo sdkInfo= BioSdk.getInfo();

Get debug data

You can save some captured data on a device's memory. In some cases, those files might help to solve some issues. Data can be found on the SD card in the SmartSDK_debug_data directory.

An example on how to configure the debug data options is shown in the snippet:

Java
1[...]
2    DebugSettingsBuilder debugSettingsBuilder = new DebugSettingsBuilder();
3    debugSettingsBuilder.logLevel(logLevel)
4          .storingType(DataStoringType.LAST_SESSION_ONLY)
5          .recordRtv(DebugOption.DISABLED)
6          .recordPostMortemRtv(DebugOption.DISABLED)
7          .saveCapturedImages(DebugOption.DISABLED);
8    captureOptions.setDebugDataSettings(debugSettingsBuilder.build());

DataStoringType can have two values: LAST_SESSION_ONLY and MULTIPLE_SESSIONS. The first one overwrites data in a single directory. The second makes a separate directory per capture.

There is also an option to store a special .rtv file that helps you understand what is happening during the capture.

Note: These files take a lot of space. LogLevel describes what part of the logs will be saved to a file. If needed, the integrator can also save captured images by enabling the saveCapturedImages option.

Returns

This is an object with the information about the SDK (refer to IBioSdkInfo).

enableAnalytics

This method turns on the reporting and sending analytics report. It also changes the analytics server and its API key.

NOTE: The server is set to Europe by default.

disableAnalytics

This turns off the reporting and sending analytics report.

Note: By default, the analytics mechanism is turned on and the server is set to Europe.

Create a DocumentCaptureHandler

This retrieves a capture handler to perform all the document capture operations. You must first configure the capture options.

• Check the use case named Read MRZ.

• Also, check all the features provided by this handler.

Java
1// Get activity from application
2    Activity activity = ...
3    // Populate a CaptureOptions object
4    IDocumentCaptureOptions captureOptions = new DocumentCaptureOptions(
5            new DocumentCaptureModeConfiguration {
6                public DocumentMode provideCaptureMode() {
7                    return DocumentMode.READ_MRZ
8            }           
9    });
10    captureOptions.setCamera(Camera.REAR);
11    captureOptions.setTorch(Torch.OFF);
12    captureOptions.setOverlay(Overlay.ON);
13    captureOptions.setCaptureTimeout(120);
14    captureOptions.enableSingleShootCapture();
15    captureOptions.setUhdResolutionEnabled(true);
16    BioSdk.createDocumentCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IDocumentCaptureHandler>() {
17        @Override
18        public void onPreExecute() {
19            // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
20        }
21        @Override
22        public void onSuccess(IDocumentCaptureHandler result) {
23            // Indicates that initialization succeeded, the returned handler can be used to start the capture.
24        }
25        @Override
26        public void onError(DocumentCaptureHandlerError e) {
27            // An error has occurred during the initialization
28        }
29    });