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 CaptureSDK is targeted to developers who want to use IDEMIA technologies within their mobile apps.

The main features are:

• Biometric captures
• Biometric coding
• Fingerprint capture and matching
• 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 Experience Portal(My Identity Proofing -> Access) 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. BioStoreDB: Repository to store biometric templates. (This component is optional, in case you don't want to implement your own database.)
4. ImageUtils: Handles the image format conversion, in case the integrator must change the image format or import an image.
5. 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.

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
• Android SDK tools: preferred latest version
• JDK: preferred latest version
• Android device (emulator is not supported)
• Minimum SDK version is 21

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. Operation with LicenseManager should be executed before starting capture.

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

Activating license

This function takes care of making sure a valid license is stored on the device. This process is crucial and must occur each time before any SDK usage. In most cases it does not require any effort from integrator side. However, it might fail in some corner cases that are listed below.

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 app is here:

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

• plugin-algorithm-f6-5-low70: Recommended algorithm for face matching, introduced in SDK version 4.44.0. There is no compatibility in the template level with other plugins.

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

More about plugins

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

XML
1<com.idemia.smartsdk.preview.CaptureView
2                        android:id="@+id/captureView"
3                        android:layout_width="match_parent"
4                        android:layout_height="match_parent" />

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

Java
1CaptureView cameraPreview = (CaptureView) findViewById(R.id.captureView);

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

6. Prepare capture settings. For finger capture, you should use FingerCaptureOptions.

Java
1FingerCaptureOptions captureOptions = new FingerCaptureOptions(BioCaptureMode.FINGERS, Hand.RIGHT);
2  captureOptions.setCamera(Camera.REAR);
3  captureOptions.setLiveness(Liveness.MEDIUM);
4  captureOptions.setCaptureTimeout(10);
5  captureOptions.setOverlay(Overlay.ON);

7. 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.createFingerCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IFingerCaptureHandler>() {
4            @Override
5            public void onPreExecute() {
6                // Optional hook on the builtin Android AsyncTask call-back `onPreExecute`
7            }
8
9            @Override
10            public void onSuccess(IFingerCaptureHandler result) {
11                // Indicates that initialization succeeded, the returned handler can be used to start the capture.
12                fingerCaptureHandler = result;
13            }
14
15            public void onError(BioCaptureHandlerError e) {
16              // An error has occurred during the initialization
17            }
18       }
19     super.onResume();
20    }

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

Java
1fingerCaptureHandler.setFingerCaptureResultListener(new FingerCaptureResultListener() {
2    @Override
3    public void onCaptureSuccess (
4        @NotNull List <MorphoImage> images, 
5        @NotNull List<FingerImagePreview> imagesToDisplay,
6        @NotNull FingerCaptureResult captureResult) {
7
8    }
9    public void onCaptureFailure (@NotNull CaptureError captureError,
10            @NotNull IBiometricInfo biometricInfo,
11            @NotNull Bundle extraInfo){
12
13    }
14});

9. 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    fingerCaptureHandler.startPreview(new PreviewStatusListener() {
2      @Override
3      public void onStarted() {
4          try {
5              fingerCaptureHandler.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   });

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

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

11. In your manifest, you must add:

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

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>

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.

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-f6-5-low70:$version'
15implementation 'com.idemia.smartsdk:plugin-algorithm-fingerv9:$version'

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.

Finger capture 

Overview 

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.

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.

Creating a BioMatcher Handler 

This allows you to retrieve a handler to perform all the matching, identifying, and template coding operations.

• Review the use cases named Create BioMatcherHandler.

• Review the features provided by this handler here.

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

Errors

You will receive an exception reporting the error.

Handlers 

This section discusses the BioCapture handler, FingerCapture handler, and BioMatcher handler.

BioCapture handler

You must retrieve the capture handler through the Biometric Capture SDK entry point.

Finger tracking listener

This sets the listener to receive feedback associated with the finger as shown in the snippet:

Java
1captureHandler.setFingerTrackingListener(new FingerCaptureTrackingListener() {
2    @Override
3    public void onTracking(@NotNull List<FingerTracking> trackingInfo) {
4
5    }
6});

Start preview

This asynchronously starts the camera preview. It is recommended to start the capture once the preview has been initialized, as shown in the snippet:

Java
Kotlin
1handler.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});

Stop preview

This stops the camera preview as shown in the snippet:

Java
1handler.stopPreview();

Start capture

This starts the biometric capture as shown in the snippet.

Java
1handler.startCapture();

Stop capture

This stops the biometric capture as shown in the snippet:

Java
1handler.stopCapture();

Switch camera

This switches between different cameras as shown in the snippet:

Java
1handler.switchCamera(Camera.FRONT); // Use front camera
2handler.switchCamera(Camera.REAR); // Use rear camera

Destroy

This releases all the handler resources as shown in the snippet:

Java
1handler.destroy();

Overlay

This sets the overlay option.

Java
1handler.setOverlay(Overlay.OFF); // Disable preview's overlay
2handler.setOverlay(Overlay.ON); // Enable preview's overlay

CaptureOptions

This retrieves the capture options used in this handler as shown in the snippet:

Java
1ICaptureOptions options = handler.getCaptureOptions();

Force capture

This forces a capture as shown in the snippet:

Java
1handler.forceCapture();

Capture handler status

Note: Check CaptureHandlerStatus.

This retrieves the status of the capture handler as shown in the snippet:

Java
1CaptureHandlerStatus captureHandlerStatus = handler.getCaptureStatus();

FingerCapture handler

You must retrieve the capture handler through the Biometric Capture SDK entry point for BioCaptureHandler as shown in the snippet:

Java
1// Get activity from application
2    Activity activity = ...
3    // Populate a CaptureOptions object
4    IFingerCaptureOptions captureOptions = new FingerCaptureOptions();
5    captureOptions.setBioCaptureMode(BioCaptureMode.ONE_FINGER);
6    captureOptions.setLiveness(Liveness.MEDIUM);
7    captureOptions.setCamera(Camera.FRONT);
8    captureOptions.setCaptureTimeout(10);
9    captureOptions.setOverlay(Overlay.OFF);
10    //////////////////////////////////
11    //Get the biometric reference
12    IBiometricReference biometricReference = ...
13    captureOptions.setBiometricReference(biometricReference);
14    //////////////////////////////////
15    BioSdk.createFingerCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IFingerCaptureHandler>() {
16        @Override
17        public void onPreExecute() {
18            // Optional hook on the builtin Android AsyncTask call-back `onPreExecute`
19        }
20
21        @Override
22        public void onSuccess(IFingerCaptureHandler result) {
23            // Indicates that initialization succeeded, the returned handler can be used to start the capture.
24            fingerCaptureHandler = result;
25        }
26        public void onError(BioCaptureHandlerError e) {
27      // An error has occurred during the initialization
28        }
29});

Note: It extends from BioCaptureHandler.

Capture result listener

This sets the listener to receive the finger captures. Hand and fingerprints images callback will be fired when the capture finishes.

Java
1fingerCaptureHandler.setFingerCaptureResultListener(new FingerCaptureResultListener() {
2        @Override
3        public void onCaptureSuccess(@NotNull List<MorphoImage> images,
4                                     @NotNull List<FingerImagePreview> imagesToDisplay,
5                                     @NotNull FingerCaptureResult captureResult) {
6        }
7        public void onCaptureFailure(@NotNull CaptureError captureError,
8                                           @NotNull IBiometricInfo biometricInfo,
9                                           @NotNull Bundle extraInfo) {
10        }
11});

FingerImagePreview

This object provides fingerprint images for display purposes.

FingerCaptureResult

setAuthenthicationListener

This is the listener to receive the callbacks related to the authentication process.

This is only compatible with AUTHENTICATION.

An example snippet is shown.

Java
1fingerCaptureHandler.setAuthenthicationListener(new BioCaptureAuthenticationListener() {
2        @Override
3        public void onAuthenticationResult(IAuthenticationResult authenticationResult) {
4            String message = getString(R.string.authentication_process);
5            message +="\n" + getString(R.string.score)+ " " +authenticationResult.getScore();
6            message +="\n" + getString(R.string.status)+ " " +authenticationResult.getStatus();
7            Toast.makeText(this, message, Toast.LENGTH_LONG).show();
8        }
9    });

Indication of optimal fingerprint distance

Methods described below may be used to improve user experience of fingerprint acquisition. They works only with specific, calibrated devices.

getCaptureDistanceRange

Returns CaptureDistanceRangeResult, which may be one of the following:

|

CaptureDistanceRange

setFingerCaptureCurrentDistanceListener

To receive the feedback about current distance between the fingers and the phone lens (e.g in order to create your own optimal distance indicator on UI), you should register listener as shown in the snippet:

Java
Kotlin
1        captureHandler.setFingerCaptureCurrentDistanceListener(new FingerCaptureCurrentDistanceListener() {
2      @Override
3      public void onCurrentCaptureDistance(@NonNull CurrentCaptureDistance currentCaptureDistance) {
4                    //handle currentCaptureDistance
5      }
6   });

CurrentCaptureDistance

setFingerCaptureFeedbackListener

Returns feedback associated with finger capture (for example if the distance between the phone lens and the fingers is optimal). Snippet below shows how to register the listener:

Java
Kotlin
1        captureHandler.setFingerCaptureFeedbackListener(new FingerCaptureFeedbackListener() {
2      @Override
3      public void onCurrentCaptureDistance(@NonNull captureInfo: FingerCaptureInfo) {
4                    //handle captureInfo
5      }
6   });

BioMatcher handler 

This interface provides all the necessary helper methods to perform all the matching, identifying, and template coding operations.

Authenticate

This verifies a list of candidate templates against a list of reference templates. This method can be used to authenticate users.

Note: Review the use cases named Authenticate.

An example snippet is shown:

Java
1//Authentication options
2IAuthenticationOptions authenticationOptions = new AuthenticationOptions();
3authenticationOptions.setThreshold(3500);
4
5//Biometric candidate
6IBiometricCandidate biometricCandidate = new BiometricCandidate(BiometricModality.FACE);
7//We add all the templates for this candidate
8biometricCandidate.addTemplates(candidates);
9
10//Biometric references
11IBiometricReference biometricReference = new BiometricReference(user.getUuid(), BiometricModality.FACE);
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});

Function

Java
1void authenticate(IAuthenticationOptions authenticationOptions, IBiometricCandidate biometricCandidate, IBiometricReference biometricReference, BioMatcherAsyncCallbacks<IAuthenticationResult> callbacks);

Errors

You will receive an exception reporting the error.

Authenticate synchronous

This verifies a list of candidate templates against a list of reference templates. This method can be used to authenticate users.

Note: This function must be executed in a different thread than the UI. Check the use cases named Authenticate.

An example snippet is shown:

Java
1//Authentication options
2IAuthenticationOptions authenticationOptions = new AuthenticationOptions();
3authenticationOptions.setThreshold(3500);
4
5//Biometric candidate
6IBiometricCandidate biometricCandidate = new BiometricCandidate(BiometricModality.FACE);
7//We add all the templates for this candidate
8biometricCandidate.addTemplates(candidates);
9
10//Biometric references
11IBiometricReference biometricReference = new BiometricReference(user.getUuid(), BiometricModality.FACE);
12//We add all the templates for this user
13biometricReference.addTemplates(references);
14
15IAuthenticationResult result = matcherHandler.authenticate(authenticationOptions, biometricCandidate, biometricReference);
16//The result of the authentication
17long resultScore = result.getScore();
18//authentication status (FAILURE, SUCCESS...)
19AuthenticationStatus authenticationStatus = authenticationResult.getStatus();

Function

An example snippet is shown.

Java
1IAuthenticationResult authenticate(IAuthenticationOptions authenticationOptions, IBiometricCandidate biometricCandidate, IBiometricReference biometricReference);

Errors

You will receive an exception reporting the error.

Identify

This method can be used to identify users. It identifies the user from the list of candidate templates that are matched against the list of reference templates.

Note: Check the use case named Identify.

An example snippet is shown:

Java
1//Identification options
2IIdentificationOptions identificationOptions = new IdentificationOptions();
3
4//Biometric candidate
5IBiometricCandidate biometricCandidate = new BiometricCandidate(BiometricModality.FACE);
6//We add all the templates for this candidate
7biometricCandidate.addTemplates(candidates);
8
9//We create the list of references
10ArrayList<IBiometricReference> biometricReferences = new ArrayList<IBiometricReference>();
11//Biometric reference for one user
12IBiometricReference biometricReference = new BiometricReference(user.getUuid(), BiometricModality.FACE);
13//We add all the templates for this user
14biometricReference.addTemplates(references);
15
16//We add the user to the list
17biometricReferences.add(biometricReference);
18
19matcherHandler.identify(identificationOptions, biometricCandidate, biometricReferences, new BioMatcherAsyncCallbacks<IIdentificationResult>() {
20    @Override
21    public void onPreExecute() {
22        // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
23    }
24
25    @Override
26    public void onSuccess(IIdentificationResult result) {
27        //The identification result
28        List<IIdentificationCandidate> candidates = result.getIdentificationCandidateList();
29        if (candidates.size() > 0) {
30            IIdentificationCandidate candidate = candidates.get(0);
31            UUID userUUID = candidate.getUuid();
32            long candidateScore = candidate.getScore();
33        }
34
35    }
36
37    @Override
38    public void onError(Exception e) {
39        // An error has occurred
40    }
41});

Function

An example snippet is shown.

Java
1void identify(IIdentificationOptions identificationOptions, IBiometricCandidate biometricCandidate, List<IBiometricReference> biometricReferences, BioMatcherAsyncCallbacks<IIdentificationResult> callbacks);

Errors

You will receive an exception reporting the error.

Identify synchronous

This method can be used to identify users.

It identifies the user from the list of candidate templates that are matched against a list of reference templates.

Note: This function must be executed in a different thread than UI. Check the use case named Identify.

An example snippet is shown.

Java
1//Identification options
2IIdentificationOptions identificationOptions = new IdentificationOptions();
3
4//Biometric candidate
5IBiometricCandidate biometricCandidate = new BiometricCandidate(BiometricModality.FACE);
6//We add all the templates for this candidate
7biometricCandidate.addTemplates(candidates);
8
9//We create the list of references
10ArrayList<IBiometricReference> biometricReferences = new ArrayList<IBiometricReference>();
11//Biometric reference for one user
12IBiometricReference biometricReference = new BiometricReference(user.getUuid(), BiometricModality.FACE);
13//We add all the templates for this user
14biometricReference.addTemplates(references);
15
16//We add the user to the list
17biometricReferences.add(biometricReference);
18
19IIdentificationResult result = matcherHandler.identify(identificationOptions, biometricCandidate, biometricReferences)
20//The identification result
21List<IIdentificationCandidate> candidates = result.getIdentificationCandidateList();
22if (candidates.size() > 0) {
23    IIdentificationCandidate candidate = candidates.get(0);
24    UUID userUUID = candidate.getUuid();
25    long candidateScore = candidate.getScore();
26}

Function

An example snippet is shown.

Java
1IIdentificationResult identify(IIdentificationOptions identificationOptions, IBiometricCandidate biometricCandidate, List<IBiometricReference> biometricReferences);

Errors

You will receive an exception reporting the error.

Detect biometrics

This allows you to detect the biometrics in a MorphoImage.

This function extracts all the biometric templates contained in an image (such as, all the faces that are in an image).

Note: Check the use case named Detect Biometric.

Java
1//Create a populate options
2    IDetectBiometricOptions detectBiometricsOptions = new DetectBiometricsOptions();
3    detectBiometricsOptions.setBiometricLocation(BiometricLocation.FACE_FRONTAL);
4    detectBiometricsOptions.setBiometricModality(BiometricModality.FACE);
5
6    bioMatcherHandler.detectBiometric(detectBiometricsOptions, image, new BioMatcherAsyncCallbacks<List<IMorphoTemplate>>() {
7        @Override
8        public void onPreExecute() {
9            // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
10        }
11
12        @Override
13        public void onSuccess(List<IMorphoTemplate> result) {
14            //A List of templates extracted from the image
15        }
16
17        @Override
18        public void onError(Exception e) {
19            // An error has occurred
20        }
21    });

Function

An example snippet is shown.

Java
1public void detectBiometric(final IDetectBiometricOptions detectBiometricsOptions, final IImage image, BioMatcherAsyncCallbacks<List<IMorphoTemplate>> callbacks)

Errors

You will receive an exception reporting the error.

Detect biometric synchronous

This allows you to detect the biometrics in a MorphoImage.

This function extracts all the biometric templates contained in an image (such as, all the faces that are in an image).

Note: This function must be executed in a different thread than the UI. Check the use case named Detect Biometric.

An example snippet is shown.

Java
1// Create a populate options
2IDetectBiometricOptions detectBiometricsOptions = new DetectBiometricsOptions();
3detectBiometricsOptions.setBiometricLocation(BiometricLocation.FACE_FRONTAL);
4detectBiometricsOptions.setBiometricModality(BiometricModality.FACE);
5
6//A List of templates extracted from the image
7List<IMorphoTemplate> templates = bioMatcherHandler.detectBiometric(detectBiometricsOptions, image);

Function

An example snippet is shown.

Java
1public List<IMorphoTemplate> detectBiometric(final IDetectBiometricOptions detectBiometricsOptions, final IImage image)

Errors

You will receive an exception reporting the error.

Destroy

This releases all the handler resources as shown in the snippet:

Java
1handler.destroy();

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 IAuthenticationResultobject 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(captureError: CaptureError, biometricInfo: IBiometricInfo, extraInfo: Bundle) {
4           // handle capture failure
5       }
6
7       // deprecated
8       override fun onCaptureSuccess(
9           images: MutableList<MorphoImage>,
10           captureResult: FingerCaptureResult
11       ) {
12          // handle capture success
13       }
14       override fun onCaptureSuccess(
15           images: List<MorphoImage>,
16           imagesToDisplay: List<FingerImagePreview>,
17           captureResult: FingerCaptureResult
18       ) {
19           // handle capture success
20       }
21   }