Skip to main content

import Changelog from './_CHANGELOG.mdx'; import ChangelogWrapper from '@site/src/components/ChangelogWrapper';

DOT Android Face Lite Integration Manual

v9.2.2​

Introduction​

DOT Android Face Lite provides components for face capture and related functionalities which are easy to integrate into an Android application.

Requirements​

DOT Android Face Lite has the following requirements:

  • Minimum Android API level 24
  • Minimum Kotlin Gradle plugin version 1.7.0 (if used)

Distribution​

Maven Repository​

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

In order to integrate DOT Android Face Lite into your project, the first step is to include the Innovatrics maven repository to your settings.gradle.kts file.

.build.gradle.kts

dependencyResolutionManagement {
    repositories {
        maven {
            url = URI("https://maven.innovatrics.com/releases")
        }
    }
}

Then, specify the dependency on DOT Android Face Lite library in the build.gradle.kts file. Dependencies of this library will be downloaded alongside the library.

.build.gradle.kts

dependencies {
    implementation("com.innovatrics.dot:dot-face-lite:$dotVersion")
}

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

.build.gradle.kts

android {
    packaging {
        resources {
            excludes += listOf(
                "**/jnidispatch.dll",
                "**/libjnidispatch.a",
                "**/libjnidispatch.jnilib",
                "**/*.proto",
            )
        }
    }
}

Supported Architectures​

DOT Android Face Lite 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.kts:

.build.gradle.kts

splits {
    abi {
        isEnable = true
        reset()
        include("arm64-v8a")
        isUniversalApk = 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.kts:

.build.gradle.kts

android {
    defaultConfig {
        applicationId = "com.innovatrics.dot.samples"
    }
}

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 Face Lite declares the following permission in AndroidManifest.xml:

.AndroidManifest.xml [source,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 DotFaceLiteLibraryConfiguration object.

https://github.com/innovatrics/dot-android-sdk-samples/blob/main/app/src/main/java/com/innovatrics/dot/samples/InitializeDotSdkUseCase.kt[InitializeDotSdkUseCase] class in the Samples project shows how to initialize DOT SDK with DotFaceLiteLibraryConfiguration. 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, https://developer.android.com/topic/performance/memory-overview#SwitchingApps[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 https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.core/-dot-sdk/is-initialized.html[`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 Face Lite 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 Face Lite components again after that point, you need to call DotSdk.initialize() again. This shouldn't be performed within the lifecycle of individual Android components.

Components​

Overview​

DOT Android Face Lite 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 Face Lite 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​

FACE DETECTOR:: A component for performing face detection on an image. FACE AUTO CAPTURE CONTROLLER:: A component for capturing good quality image of human face.

List of UI Components​

UI FACE AUTO CAPTURE:: A visual component for capturing good quality images of a human face. UI MAGNIFEYE LIVENESS (deprecated):: A visual component for capturing images suitable for MagnifEye liveness evaluation. UI MULTI-RANGE LIVENESS:: A visual component for capturing images suitable for Multi-Range Liveness evaluation.

Non-UI Components​

Face Detector​

The FaceDetector interface provides a face detection functionality.

Create a FaceDetector:

val faceDetector = FaceDetectorFactory.create()

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

val result = faceDetector.detect(image)

Face Auto Capture Controller​

The FaceAutoCaptureController interface provides a stateful face auto capture functionality.

Create FaceAutoCaptureController:

val configuration = FaceAutoCaptureController.Configuration(
    detectionArea = detectionArea,
    //…
)
val faceAutoCaptureController = FaceAutoCaptureControllerFactory.create(configuration)

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

val processingResult = faceAutoCaptureController.process(image, timestampMillis)

The controller evaluates the image requirements for each sample (frame). Once there are https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.core.ui.configuration/-auto-capture-configuration/min-valid-samples-in-row-to-start-candidate-selection.html[minValidSamplesInRowToStartCandidateSelection] valid samples in a row, candidate selection is started with duration of https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.core.ui.configuration/-auto-capture-configuration/candidate-selection-duration-millis.html[candidateSelectionDurationMillis] milliseconds. After the candidate selection is finished, the best face image candidate is returned and the face auto capture process is over.

UI Components​

[[fragment-configuration]]

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 DemoFaceAutoCaptureFragment : FaceAutoCaptureFragment() {

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

    //…
}

The FaceAutoCaptureFragment 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 https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-face-auto-capture-fragment/-configuration/index.html[FaceAutoCaptureFragment.Configuration] data class with the desired parameters.

class DemoFaceAutoCaptureFragment : FaceAutoCaptureFragment() {

    override fun provideConfiguration() = Configuration(
        placeholder = Placeholder.Visible(
            type = configuration.placeholderType,
        ),
        isDetectionLayerVisible = configuration.isDetectionLayerVisible,
        //…
    )

    //…
}

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 - https://developer.android.com/reference/androidx/activity/result/contract/ActivityResultContracts.RequestPermission[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 https://developer.android.com/guide/topics/ui/multi-window[multi-window mode] correctly, configure the activity in your AndroidManifest.xml file as follows:

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

Video Recording for Identity Proofing​

UI components support video recording. You can enable this feature in the component’s configuration using the isVideoCaptureEnabled parameter. The duration of the captured video is limited to a maximum of 8 seconds, corresponding to the end of the processing session. The captured video is bundled into the component’s result binary content and can be retrieved via the Digital Identity Service (DIS) for the purposes of https://developers.innovatrics.com/digital-onboarding/docs/functionalities/trust/identity-proofing/[Identity proofing].

UI Face Auto Capture​

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

In order to configure the behaviour of FaceAutoCaptureFragment, use https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-face-auto-capture-fragment/-configuration/index.html[`FaceAutoCaptureFragment.Configuration`] (see fragment-configuration). For face verification scenarios, a convenient preset configuration https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-face-auto-capture-fragment/-configuration/-presets/simple.html[`simple`] is available within https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-face-auto-capture-fragment/-configuration/-presets/index.html[`FaceAutoCaptureFragment.Configuration.Presets`].

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

Start the face auto capture process:

  1. Check whether DOT Android Face Lite is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face Lite is no longer initialized and the face auto capture process must not be started.
  2. If DOT Android Face Lite is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face Lite and then call start().

When the face auto capture process finishes successfully, the result will be returned via the onFinished() callback.

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

Call start() method again in case you need to start over the face auto capture process. You can also call start() method to stop and start over ongoing process as well.

In case you want to stop the face auto capture process prematurely, call the stop() method.

Quality Attributes of the Output Image​

You may adjust quality requirements for the output image. To perform this, you can use pre-defined instances - https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture/-quality-attribute-thresholds/index.html[`QualityAttributeThresholds`] - from https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture/-quality-attribute-thresholds/-presets/index.html[`QualityAttributeThresholds.Presets`] with recommended thresholds and pass it to https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-face-auto-capture-fragment/-configuration/index.html[`FaceAutoCaptureFragment.Configuration`] by setting the https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture.ui/-base-face-auto-capture-fragment/-configuration/quality-attribute-thresholds.html[`qualityAttributeThresholds`]. You can also create your own instance of https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture/-quality-attribute-thresholds/index.html[`QualityAttributeThresholds`] from scratch or based on pre-defined instances according to your needs.

Possible ways how to create https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture/-quality-attribute-thresholds/index.html[`QualityAttributeThresholds`]:

// The standard preset
val standard = QualityAttributeThresholds.Presets.standard

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

// Custom thresholds
val custom = QualityAttributeThresholds(
    minConfidence = minConfidence,
    maxDevicePitchAngle = maxDevicePitchAngle,
)

Available presets (pre-defined instances with thresholds) in https://innovatrics.github.io/dot-android-sdk-api-docs/face-lite/latest/dot-face-lite/com.innovatrics.dot.face.lite.autocapture/-quality-attribute-thresholds/-presets/index.html[`QualityAttributeThresholds.Presets`]:

UI MagnifEye Liveness (deprecated)​

warning

This component is deprecated in favour of UI Multi-Range Liveness.

The fragment with instructions for obtaining face data suitable for MagnifEye liveness evaluation.

In order to configure the behaviour of MagnifEyeLivenessFragment, use MagnifEyeLivenessFragment.Configuration (see fragment-configuration).

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

Start the MagnifEye liveness process:

  1. Check whether DOT Android Face Lite is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face Lite is no longer initialized and the MagnifEye liveness process must not be started.
  2. If DOT Android Face Lite is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face Lite and then call start().

When the MagnifEye liveness process finishes successfully, the result will be returned via the onFinished() callback.

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

UI Multi-Range Liveness​

The fragment with instructions for obtaining face data suitable for Multi-Range Liveness evaluation.

In order to configure the behaviour of MultiRangeLivenessFragment, use MultiRangeLivenessFragment.Configuration (see fragment-configuration). This configuration requires a list of MultiRangeLivenessChallengeItem. You should obtain this list from the DIS (Digital Identity Service).

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

Start the Multi-Range liveness process:

  1. Check whether DOT Android Face Lite is initialized. This step is important, because Android OS can terminate an application running in background in order to free resources and then it creates an instance of the top activity in the activity stack. At this point the DOT Android Face Lite is no longer initialized and the Multi-Range liveness process must not be started.
  2. If DOT Android Face Lite is initialized, you can call the start() method immediately. If not, you need to initialize DOT Android Face Lite and then call start().

When the Multi-Range Liveness process finishes successfully, the result will be returned via the onFinished() callback.

In case you want to stop the Multi-Range Liveness process prematurely, call the stop() method. The callback in the method argument indicates that the processing is over.

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_face_face_auto_capture_instruction_brightness_too_high"\>Turn towards light\</string\>
\<string name="dot_face_face_auto_capture_instruction_brightness_too_low"\>Turn towards light\</string\>
\<string name="dot_face_face_auto_capture_instruction_candidate_selection"\>Stay still…\</string\>
\<string name="dot_face_face_auto_capture_instruction_device_pitch_too_high"\>Hold your phone at eye level\</string\>
\<string name="dot_face_face_auto_capture_instruction_face_not_detected"\>Position your face into the circle\</string\>
\<string name="dot_face_face_auto_capture_instruction_face_out_of_bounds"\>Center your face\</string\>
\<string name="dot_face_face_auto_capture_instruction_sharpness_too_low"\>Turn towards light\</string\>
\<string name="dot_face_face_auto_capture_instruction_size_too_large"\>Move back\</string\>
\<string name="dot_face_face_auto_capture_instruction_size_too_large_escalated"\>Move your face back\</string\>
\<string name="dot_face_face_auto_capture_instruction_size_too_small"\>Move closer\</string\>
\<string name="dot_face_face_auto_capture_instruction_size_too_small_escalated"\>Move your face closer\</string\>
Colors​

You may customize the colors used by DOT Android Face Lite 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" /\>

Security guidelines​

Our video injection prevention feature relies heavily on following established security best practices as outlined in the Android Developer website's https://developer.android.com/privacy-and-security/security-tips[Security guidelines]. Specifically, the https://developer.android.com/privacy-and-security/security-tips#app_integrity[App Integrity] and https://developer.android.com/privacy-and-security/security-tips#networking[Networking] sections provide crucial foundations for this functionality. The https://developer.android.com/google/play/integrity[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 https://mas.owasp.org/[OWASP Mobile Application Security (MAS)] flagship project provides a security standard for mobile apps (https://mas.owasp.org/MASVS/[OWASP MASVS]) and a comprehensive testing guide (https://mas.owasp.org/MASTG/[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.

<<<

Appendix​