DOT Android Document library

v8.5.2

Introduction

DOT Android Document provides components for document capture and related functionalities which are easy to integrate into an Android application.

Requirements

DOT Android Document has the following requirements:

Minimum Android API level 21
Minimum Kotlin Gradle plugin version 1.6.0 (if used)

Distribution

Maven Repository

DOT Android Document is distributed as an Android library (.aar package) stored in the Innovatrics maven repository.

In order to integrate DOT Android Document into your project, the first step is to include the Innovatrics maven repository and Google repository to your top level build.gradle file.

build.gradle

allprojects {
    repositories {
        maven {
            url 'https://maven.innovatrics.com/releases'
        }
    }
}

Then, specify the dependency on DOT Android Document library in the module’s build.gradle file. Dependencies of this library will be downloaded alongside the library.

build.gradle

dependencies {
    //…
    implementation "com.innovatrics.dot:dot-document:$dotVersion"
    //…
}

In order to optimize application size, we also recommend adding the following excludes to your application’s build.gradle file.

build.gradle

android {
    //…
    packagingOptions {
        exclude("**/libjnidispatch.a")
        exclude("**/jnidispatch.dll")
        exclude("**/libjnidispatch.jnilib")
        exclude("**/*.proto")
    }
}

Supported Architectures

DOT Android Document provides binaries for these architectures:

armeabi-v7a
arm64-v8a
x86
x86_64

If your target application format is APK and not Android App Bundle, and the APK splits are not specified, the generated APK file will contain binaries for all available architectures. Therefore we recommend to use APK splits. For example, to generate arm64-v8a APK, add the following section into your module build.gradle:

build.gradle

splits {
    abi {
        enable true
        reset()
        include 'arm64-v8a'
        universalApk false
    }
}

If you do not specify this section, the resulting application can become too large in size.

Licensing

In order to use DOT SDK in other apps, it must be licensed. The license can be compiled into the application as it is bound to the application ID specified in build.gradle:

build.gradle

defaultConfig {
    applicationId "com.innovatrics.dot.sample"
    //…
}

The application ID can be also retrieved in runtime by calling DotSdk.getApplicationId().

In order to obtain the license, please contact your Innovatrics’ representative specifying the application ID. If the application uses build flavors with different application IDs, each flavor must contain a separate license. Put the license file into the raw resource folder.

Permissions

DOT Android Document declares the following permission in AndroidManifest.xml:

AndroidManifest.xml

<uses-permission android:name="android.permission.CAMERA" />

Basic Setup

Initialization

Before using any of the components, you need to initialize DOT SDK with the license and DotDocumentLibrary object.

InitializeDotSdkUseCase class in the Samples project shows how to initialize DOT SDK with DotDocumentLibrary. DotSdk.initialize() method should be called on background thread.

Keep in mind that if you try to use any component without initialization, it will throw an exception. Also be aware that while the app is in background, the system may kill the process to free resources. In such a case, you need to reinitialize the SDK when the app is brought back to the foreground. We recommend to check the SDK initialization status (using DotSdk.isInitialized() method) in your Fragment’s onViewCreated(). This technique is implemented in the Samples project.

Deinitialization

When a process (e.g. onboarding) using the DOT Android Document has been completed, it is usually a good practice to free the resources used by it.

You can perform this by calling DotSdk.deinitialize(). If you want to use the DOT Android Document components again after that point, you need to call DotSdk.initialize() again. This shouldn’t be performed within the lifecycle of individual Android components.

Logging

Although logging is disabled by default, it can be enabled explicitly by using the following method from the com.innovatrics.dot.core.Logger class.

Logger.setLoggingEnabled(true)

The appropriate place for this call is within the onCreate() method of your subclass of android.app.Application. Each TAG of a log message starts with the prefix dot-document:.

This setting enables logging for all DOT Android libraries.

Keep in mind that logging should be used just for debug purposes as it might produce a lot of log messages.

Components

Overview

DOT Android Document provides both non-UI and UI components. Non-UI components are aimed to be used by developers who want to build their own UI using the DOT Android Document functionality. UI components are build on top of non-UI components. These are available as abstract fragments and can be extended and then embedded into the application’s existing activity providing more control.

List of Non-UI Components

DOCUMENT DETECTOR: A component for performing document detection on an image.
IMAGE PARAMETERS ANALYZER: A component for computing image parameters such as sharpness, brightness or hotspots score.
IMAGE PERSPECTIVE WARPER: A component for perspective warping an image according detected document position.
DOCUMENT AUTO CAPTURE CONTROLLER: A component for capturing good quality images suitable for optical character recognition.
MACHINE READABLE ZONE READER: A component for reading Machine Readable Zone (MRZ).

List of UI Components

DOCUMENT AUTO CAPTURE: A visual component for capturing good quality images suitable for optical character recognition.

Non-UI Components

Document Detector

The DocumentDetector interface provides a document detection functionality.

Create a DocumentDetector:

val documentDetector = DocumentDetectorFactory.create()

To perform detection, call the following method on the background thread:

val document = documentDetector.detect(bgraRawImage)

Image Parameters Analyzer

The ImageParametersAnalyzer interface provides an image parameters analysis functionality.

Create ImageParametersAnalyzer:

val imageParametersAnalyzer = ImageParametersAnalyzerFactory.create()

To perform analysis, call the following method on the background thread:

val imageParameters = imageParametersAnalyzer.analyze(bgraRawImage)

Image Perspective Warper

The ImagePerspectiveWarper interface provides perspective warping functionality.

Create ImagePerspectiveWarper:

val imagePerspectiveWarper = ImagePerspectiveWarperFactory.create()

To perform perspective warping, call the following method on the background thread:

val warpedBgraRawImage = imagePerspectiveWarper.warp(bgraRawImage, detectionPosition, targetImageSize)

Document Auto Capture Controller

The DocumentAutoCaptureController interface provides a stateful document auto capture functionality.

Create DocumentAutoCaptureController:

val configuration = DocumentAutoCaptureController.Configuration(
    context = context,
    validators = validators,
    //…
)
val documentAutoCaptureController = DocumentAutoCaptureControllerFactory.create(configuration)

You can use detectionNormalizedRectangle to specify the region in the input image which will be used for document detection. For example, if you want to ignore top 30% and bottom 30% of the input image, you can do it as follows:

val configuration = DocumentAutoCaptureController.Configuration(
    context = context,
    validators = validators,
    detectionNormalizedRectangle = RectangleDouble(0.0, 0.3, 1.0, 0.7),
    //…
)

If detectionNormalizedRectangle is not specified, the source input image is used for document detection.

To capture a good quality document image, repeatedly call the process() method using the camera frames:

val processingResult = documentAutoCaptureController.process(bgraRawImage, timestampMillis)

The controller evaluates the image requirements for each frame. Once there are minValidFramesInRowToStartCandidateSelection valid frames in a row, candidate selection is started with duration of candidateSelectionDurationMillis milliseconds. After the candidate selection is finished, the best document image candidate is returned and the document auto capture process is over.

Machine Readable Zone Reader

The MrzReader interface provides a Machine Readable Zone (MRZ) reading functionality.

Create MrzReader:

val configuration = MrzReader.Configuration(context)
val mrzReader = MrzReaderFactory.create(configuration)

To read a MRZ, call the following method on the background thread:

val result = mrzReader.read(bgraRawImage, document)

Or, alternatively if you know the travel document type call this method in order to increase precision of reading:

val result = mrzReader.read(bgraRawImage, document, travelDocumentType)

Argument document is a product of either Document Detector component, Document Auto Capture Controller component or Document Auto Capture UI component.

The result of successful MRZ reading contains travel document type and machine readable zone. If MRZ reading was not successful, the result will contain an exception and travelDocumentType and/or machineReadableZone may be null.

UI Components

Fragment Configuration

Components containing UI are embedded into the application as fragments from Android Support Library. All fragments are abstract. They must be subclassed and override their abstract methods.

Fragments requiring runtime interaction provide public methods, for example start().

class DemoDocumentAutoCaptureFragment : DocumentAutoCaptureFragment() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        start()
    }

    //…
}

The DocumentAutoCaptureFragment requires a configuration. To provide configuration data, you should override the provideConfiguration() method in your subclass implementation. This method should return an instance of the DocumentAutoCaptureFragment.Configuration data class with the desired parameters.

class DemoDocumentAutoCaptureFragment : DocumentAutoCaptureFragment() {

    override fun provideConfiguration() = Configuration(
        cameraFacing = CameraFacing.BACK,
        cameraPreviewScaleType = CameraPreviewScaleType.FIT,
        //…
    )

    //…
}

Camera permission

A fragment (UI component) will check the camera permission (Manifest.permission.CAMERA) right before the camera is started. If the camera permission is granted the fragment will start the camera. If the camera permission is not granted the fragment will use Android API - ActivityResultContracts.RequestPermission to request the camera permission. Android OS will present the system dialog to the user of the app. If the user explicitly denies the permission at this point, onNoCameraPermission() callback is called. Implement this callback in order to navigate the user further in your app workflow.

Orientation Change

In order to handle the orientation change in multi-window mode correctly, configure the activity in your AndroidManifest.xml file as follows:

<activity
    android:name=".MyActivity"
    android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation" />

Document Auto Capture

The fragment with instructions for obtaining quality document images suitable for further processing.

In order to configure the behaviour of DocumentAutoCaptureFragment, use DocumentAutoCaptureFragment.Configuration (see Fragment Configuration).

To use the fragment, create a subclass of DocumentAutoCaptureFragment and override appropriate callbacks.

To start the document auto capture process call the start() method. You can start the process any time.

In case you want to handle detection data, implement onProcessed() callback. This callback is called with each processed camera frame. When the document auto capture process finishes successfully, the result will be returned via the onCaptured() callback.

In case you want to force the capture event, call the requestCapture() method. The most recent image will be returned via the onCaptured() callback asynchronously.

Call start() method again in case you need to start over the document auto capture process (e.g. you want to capture both sides of the document, one after another). You can also call start() method to stop and start over ongoing process as well.

In case you want to stop the document auto capture process prematurely, call the stopAsync() method. The callback in the method argument indicates that the processing is over.

Quality Attributes of the Output Image

You may adjust quality requirements for the output image. To perform this, you can use pre-defined instances - QualityAttributeThresholds - from QualityAttributeThresholdPresets with recommended thresholds and pass it to DocumentAutoCaptureFragment.Configuration by setting the qualityAttributeThresholds. You can also create your own instance of QualityAttributeThresholds from scratch or based on pre-defined instances according to your needs.

Possible ways how to create QualityAttributeThresholds:

// The standard preset
val standard = QualityAttributeThresholdPresets.standard

// Modified thresholds based on the standard preset
val modified = standard.copy(
    minConfidence = minConfidence,
    minSharpness = null,
)

// Custom thresholds
val custom = QualityAttributeThresholds(
    minConfidence = minConfidence,
    minSharpness = null,
)

Available presets (pre-defined instances with thresholds) in QualityAttributeThresholdPresets:

standard - The resulting image suitable for evaluation on Digital Identity Service. See the thresholds.

Customization of UI components

Strings

You can override the string resources in your application and provide alternative strings for supported languages using the standard Android localization mechanism.

<string name="dot_document_auto_capture_instruction_brightness_too_high">Less light needed</string>
<string name="dot_document_auto_capture_instruction_brightness_too_low">More light needed</string>
<string name="dot_document_auto_capture_instruction_candidate_selection">Hold still…</string>
<string name="dot_document_auto_capture_instruction_document_does_not_fit_placeholder">Center document</string>
<string name="dot_document_auto_capture_instruction_document_not_detected">Scan document</string>
<string name="dot_document_auto_capture_instruction_document_out_of_bounds">Center document</string>
<string name="dot_document_auto_capture_instruction_hotspots_score_too_high">Avoid reflections</string>
<string name="dot_document_auto_capture_instruction_mrz_not_present">Scan valid machine readable document</string>
<string name="dot_document_auto_capture_instruction_mrz_not_valid">Scan valid machine readable document</string>
<string name="dot_document_auto_capture_instruction_sharpness_too_low">More light needed</string>
<string name="dot_document_auto_capture_instruction_size_too_small">Move closer</string>

Colors

You may customize the colors used by DOT Android Document in your application. To use custom colors, override the specific color.

<color name="dot_detection_layer">#ffffffff</color>
<color name="dot_instruction_background">#fff8fbfb</color>
<color name="dot_instruction_candidate_selection_background">#ff00bfb2</color>
<color name="dot_instruction_candidate_selection_text">#ff131313</color>
<color name="dot_instruction_text">#ff131313</color>
<color name="dot_placeholder">#ffffffff</color>
<color name="dot_placeholder_candidate_selection">#ff00bfb2</color>
<color name="dot_placeholder_overlay">#80131313</color>

Styles

Text views and buttons can be styled by overriding the parent style in the application.

<style name="TextAppearance.Dot.Medium" parent="TextAppearance.AppCompat.Medium" />
<style name="TextAppearance.Dot.Medium.Instruction" />

Common Classes

`ImageSize`

DTO which represents a size of an image. To create an instance:

val imageSize = ImageSize(width, height)

`BgraRawImage`

DTO which represents and an image. To create an instance:

val bgraRawImage = BgraRawImage(size, bytes)

To create an instance from Bitmap:

val bgraRawImage = BgraRawImageFactory.create(bitmap)

`DetectionPosition`

DTO which represents a position of a detected document. To create an instance:

val detectionPosition = DetectionPosition(topLeft, topRight, bottomRight, bottomLeft)

Security guidelines

Our video injection prevention feature relies heavily on following established security best practices as outlined in the Android Developer website’s Security guidelines. Specifically, the App Integrity and Networking sections provide crucial foundations for this functionality. The Play Integrity API ensures your app binary remains unaltered, preventing potential vulnerabilities that could be exploited for video injection. Networking Security guidelines help secure communication channels. These guidelines help prevent unauthorized modification of data streams. By adhering to these security principles, you create a robust environment where our video injection prevention features can function optimally, safeguarding you from tampered content.

OWASP Mobile Application Security

We also strongly recommend following the OWASP Mobile Application Security guidelines. The OWASP Mobile Application Security (MAS) flagship project provides a security standard for mobile apps (OWASP MASVS) and a comprehensive testing guide (OWASP MASTG) that covers the processes, techniques, and tools used during a mobile app security test, as well as an exhaustive set of test cases that enables testers to deliver consistent and complete results.

MRZ parsing issue.

DOT Android Document library

v8.5.2#

v8.5.2