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 (see: FaceCapture and FingerCapture): Handles the capture of the biometrics through the camera of the device.
2. BioMatcherHandler (see: FaceCapture and_FingerCapture_: Handles the biometric coding and matching.
3. DocumentCaptureHandler: Handles the document reading features (like reading MRZ documents).
4. BioStoreDB_ (see: FaceCapture and _FingerCapture]: 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 DocumentCaptureHandler is through the Document 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 {....ndk.abiFilters 'armeabi-v7a','arm64-v8a'}

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

Kotlin
1val 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

Document capture - remote (recommended) 

Introduction 

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

Integration 

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

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

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

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

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

4. 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        timeoutListener
7    ),
8    lifecycle
9)

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.

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.

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.

CaptureTimeoutListener

Returns images in case of document capture timeout. Those images can be shown with associated _DocumentImageQualityIndicators to make another capture easeier. NOTE: _DocumentImageQualityIndicators from Failure are applicable ONLY for the last image returned on this callback!

Kotlin
1private val timeoutListener = CaptureTimeoutListener { documentImages ->
2        // Show images to the user
3    }

This listener is optional.

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.

Document capture - local 

Getting Started 

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

Downloadable sample app are at Document autocapture.

To create your own app:

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

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

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

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

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

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

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

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.

Kotlin
1val 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. 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.setCamera(Camera.REAR);
12           captureOptions.setOverlay(Overlay.ON);
13           captureOptions.setCaptureTimeout(120);
14           BioSdk.createDocumentCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IDocumentCaptureHandler>() {
15               @Override
16               public void onPreExecute() {
17                   // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
18               }
19               @Override
20               public void onSuccess(IDocumentCaptureHandler result) {
21                   // Indicates that initialization succeeded, the returned handler can be used to start the capture.
22               }
23               @Override
24               public void onError(BioCaptureHandlerError e) {
25                   // An error has occurred during the initialization
26               }
27           });
28          super.onResume();
29       }

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_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-->
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>

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

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

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

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.setOverlay(Overlay.ON);
12    captureOptions.setCaptureTimeout(120);
13    captureOptions.enableSingleShootCapture();
14    captureOptions.setUhdResolutionEnabled(true);
15    BioSdk.createDocumentCaptureHandler(activity, captureOptions, new MscAsyncCallbacks<IDocumentCaptureHandler>() {
16        @Override
17        public void onPreExecute() {
18            // Optional hook on the builtin Android AsyncTask callback `onPreExecute`
19        }
20        @Override
21        public void onSuccess(IDocumentCaptureHandler result) {
22            // Indicates that initialization succeeded, the returned handler can be used to start the capture.
23        }
24        @Override
25        public void onError(DocumentCaptureHandlerError e) {
26            // An error has occurred during the initialization
27        }
28    });

Errors 

Document capture handler 

You must retrieve the capture handler through Create DocumentCaptureHandler.

Document capture listener

This sets the listener to receive the captures.

The events of the capture process are reported to the integrator app through this listener, as shown in the snippet below:

Java
1captureHandler.setDocumentCaptureListener(new DocumentCaptureListener() {
2        @Override
3        public void onCaptureImageDocument(DocumentImage image) {
4            //Document image captured
5            try {
6                byte[] jpegImage = image.getJPEGImage();
7                Bitmap documentImage = BitmapFactory.decodeByteArray(jpegImage, 0, jpegImage.length);
8                //show the document image
9            }catch (Exception e){
10                Log.e(TAG, "", e);
11            }
12        }
13        @Override
14        public void onCaptureFieldImageDocument(DocumentImage image, String labelName) {
15            //A field has been coded
16        }
17        @Override
18        public void onMRZDocumentRead(List<IMRZLine> mrzLines) {
19            //MRZ captured
20        }
21        @Override
22        public void onDocumentCaptureFailure(DocumentCaptureError captureError, DocumentImageQualityIndicators indicators) {
23            //Capture failed
24        }
25        @Override
26        public void onCaptureFinish() {
27            //Capture finished
28        }
29    });

Barcode capture listener

This sets the listener to receive the barcode captures. The events of the capture process are reported to the integrator app through this listener.

There are two types of listeners: text data and raw data.

Java
1//Barcode callbacks for text data
2    captureHandler.setBarcodeListener(new BarcodeListener() {
3        @Override
4        public void onBarcodeRead(List<String> capture){
5            //Barcode captured
6        }
7        @Override
8        public void onDocumentCaptureFailure(DocumentCaptureError captureError, DocumentImageQualityIndicators indicators) {
9            //Capture failed
10        }
11        @Override
12        public void onCaptureFinish() {
13            //Capture finished
14        }
15    });

Java
1//Barcode callbacks for raw data
2    captureHandler.setBarcodeListener(new BarcodeListener(){
3        @Override
4        public void onBarcodeRead(RTBuffer capture){
5            //Barcode captured
6        }
7        @Override
8        public void onDocumentCaptureFailure(DocumentCaptureError captureError, DocumentImageQualityIndicators indicators)  {
9            //Capture failed
10        }
11        @Override
12        public void onCaptureFinish() {
13            //Capture finished
14        }
15    });

Only one listener can be active at a time.

Feedback listener

This sets the listener to receive feedback, like moving a face to the right.

Java
1captureHandler.setDocCaptureFeedbackListener(new DocumentCaptureFeedbackListener() {
2    @Override
3    public void onCaptureInfo (DocCaptureInfo docCaptureInfo){
4        //Document captures info
5    }
6});

VideoRecordingReadyForGenerationListener

This sets the listener for a document to get VideoRecording. This listener is called when recording is enabled. It is called on successful and failed capture.

Set callback as shown in the snippet:

Java
1captureHandler.setVideoRecordingReadyForGenerationListener(new VideoRecordingReadyForGenerationListener() {
2
3        @Override
4        public void videoRecordingReadyForGeneration(VideoRecording videoRecording) {
5            //Video recording object to generate video
6        }
7    });

Callback returns VideoRecording object to generate video from capture.

Start preview

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 as shown in the snippet:

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
1IDocumentCaptureOptions options = handler.getCaptureOptions();

Force capture

This forces a capture as shown in the snippet:

Java
1handler.forceCapture();

Capture handler status

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

Java
1CaptureHandlerStatus captureHandlerStatus = handler.getCaptureStatus();

Note: Refer to CaptureHandlerStatus.

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.

Helper objects 

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.

BioSdk class - 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.

BioSdk class - 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.

This section describes the helper objects that are necessary to use the Biometric Capture SDK.

MscAsyncCallbacks

Generic callbacks which execute task asynchronous.

Function

Kotlin
1fun onPreExecute() {
2
3}

Function

Kotlin
1fun onSuccess(result: T) {
2    //on success
3}

Arguments

Function

Kotlin
1fun onError(e: BioCaptureHandlerError) {
2    //on success
3}

Arguments

IBioSdkInfo

This object exposes information about the SDK.

DocumentCaptureOptions

This object is used to configure the behavior of the DocumentCapture.

IImage

This is the image interface that the SDK image objects extend.

IDocumentImage

This is the document image interface that the SDK document image objects extend. It extends from IImage, but getImageQuality() method of IImage will always return -1 for document image.

DocumentImageQualityIndicators

This object contains failure reasons of the capture.

MorphoDocumentRegion

This object contains the coordinates of the document.

IMrzRecord

The MRZ record that interfaces with the SDK MRZ record objects that are extended.

IMrzFrenchIdCardRecord

The MRZ record interface for French identity cards. It extends IMrzRecord.

IMrzMRPRecord

The MRZ record interface for MRP cards. It extends IMrzRecord.

IMrzMrtdTd1Record

The MRZ record interface for MRTD TD1 cards. It extends IMrzRecord.

IMrzMrtdTd2Record

The MRZ record interface for MRTD TD2 cards. It extends IMrzRecord.

IMrzMrvARecord

The MRZ record interface for MRV A cards. It extends IMrzRecord.

IMrzMrvBRecord

The MRZ record interface for MRV B cards. It extends IMrzRecord.

IMrzSlovackId2_34Record

The MRZ record interface for Slovakian identity cards. It extends IMrzRecord.

GenericDocumentCaptureListener

This is a generic capture listener.

onDocumentCaptureFailure

This is invoked if DocumentCaptureHandler fails to do a capture. Check DocumentCaptureError.

Function

Java
1void onDocumentCaptureFailure(@NonNull DocumentCaptureError captureError, @Nullable DocumentImageQualityIndicators indicators);

Arguments

onCaptureFinish

This is invoked by DocumentCaptureHandler when it finishes the capture process.

Function

Java
1void onCaptureFinish();

DocumentCaptureListener

This is the document capture listener that extends GenericDocumentCaptureListener.

onCaptureImageDocument

This is invoked if a successful document image has been captured. Check DocumentImage.

Function

Java
1void onCaptureImageDocument(DocumentImage image);

Arguments

onCaptureFieldImageDocument

This is invoked if a document field has been captured. Check DocumentImage.

Function

Java
1void onCaptureFieldImageDocument(DocumentImage image, String labelName);

Arguments

onMRZDocumentRead

This is invoked by DocumentCaptureHandler when it finishes reading all the lines of an MRZ document. Check IMRZLine.

Function

Java
1void onMRZDocumentRead(List<IMRZLine> mrzLines, IMrzRecord mrzRecord);

Arguments

BarcodeListener

This is the barcode capture listener that extends GenericDocumentCaptureListener.

onBarcodeRead

This is invoked if a successful barcode has been read.

Function

Java
1void onBarcodeRead(List<String> capture);

Arguments

Function

Java
1void onBarcodeRead(RTBuffer capture);

Arguments

DocumentCaptureFeedbackListener

This is the capture feedback listener. This listener enables the app to receive feedback about the document captures, such as image blur.

onCaptureInfo

This is invoked multiple times by DocumentCapture to send feedback about the capture process to the app.

Function

An example snippet is shown:

Java
1void onCaptureInfo(DocCaptureInfo docCaptureInfo);

Arguments

DocumentCaptureTrackingListener

Tracking listener

This sets the listener to receive tracking information, such as where the biometric is located.

Java
1captureHandler.setDocumentTrackingListener(new DocumentCaptureTrackingListener() {
2    @Override
3    public void onTracking (List < MorphoDocumentRegion > trackingInfo) {
4        //Tracking info to know where the document is.
5    }
6});

IMRZLine

This interface represents a basic MRZ line.

CaptureListener

This is a generic capture listener.

onCaptureFinish

This is invoked by DocumentCaptureHandler when the capture finishes.

Function

An example snippet is shown:

Java
1void onCaptureFinish();

VideoRecordingOptions

This object is used to configure the behavior of the VideoRecording. You cannot generate two or more videos at the same time.

VideoRecording

This object is used to generate video in MP4 format. On success, it return the path to the video. You can generate one video.

Java
1videoRecording.generateVideo(new VideoProgressListener() {
2    
3    @Overide
4    void onFinish(String path) {
5        //When creating video comlete with success return path to video
6    }
7
8    @Overide
9    void progress(int progress) {
10        //Showing progress of generating video from 0 to 100
11    }
12
13    @Overide
14    void onError(VideoError error) {
15        //It's call when generating video failed or another video is current generating
16    }
17});

Rectification

This is the enum used to configure the rectification for the capture.

DocumentCaptureMode

This is the enum used to configure the mode for the capture.

AcquisitionMode

This enum is used for configure document capture quality mode

DocumentCaptureError

This enum reports why the document capture fails.

DocCaptureInfo

This enum reports the document capture information.

DocumentLocation

This enum shows biometric locations.

MorphoMrzDocumentCode

This enum retrieves the MRZ document code.

MorphoMrzDocumentFormat

This enum retrieves the MRZ document format.

MorphoMrzSex

This enum retrieves the MRZ document gender.

CodedMode

This enum shows document image capture modes. These indicate how the image has been triggered.

DocLevel

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

DocumentImageQualityIndicator

This enums gives information about quality indicator

Compression recommendations 

The recommendations for document images are:

• Send non-segmented images.
• Compression is JPEG92
• Size of image will be about 1 MB

An example snippet is shown:

Kotlin
1val JPEG_COMPRESSION_LEVEL = 92
2
3private fun prepareImage(image:ByteArray): ByteArray {
4    val byteArrayOutStream = ByteArrayOutputStream()
5    val documentBitmap = BitmapFactory.decodeByteArray(image, 0, image.size)
6    val result = documentBitmap.compress(Bitmap.CompressFormat.JPEG, JPEG_COMPRESSION_LEVEL, byteArrayOutStream)
7    documentBitmap.recycle()
8
9    return byteArrayOutStream.toByteArray()
10}

Remember to use only ImageUtils for any image transformation/compression - especially when IDEMIA backend is being used. The common mistake is to convert images to Android's Bitmap object (for UI purposes) and then send them to the backend. It might lead to some side effects, so please try to avoid this.