BlinkID Verify SDK for Android

The BlinkID Verify Android SDK is a comprehensive solution for implementing secure document scanning and verification on Android. It offers powerful capabilities for capturing, analyzing, and verifying a wide range of identification documents.

Table of contents

• Quick Start
  • Quick start with the sample app
  • SDK integration
• Device requirements
  • Android version
  • Camera
  • Processor architecture
• Pre-bundling the SDK resources in your app
• Customizing the look and UX
  • Simple customizations
  • Advanced customizations
• Changing default strings and localization
  • Defining your own string resources for UI elements
• Completely custom UX (advanced)
  • The BlinkIdVerifySdk and CaptureSession
• Troubleshooting
• Additional info
  • BlinkID Verify SDK size
  • API documentation
  • Contact

Quick Start

Quick start with the sample apps

1. Open Android Studio.
2. In Quick Start dialog choose Open project.
3. In File dialog select BlinkIDVerify folder.
4. Wait for the project to load. If Android Studio asks you to reload the project on startup, select Yes.

Included sample apps:

• app demonstrates quick and straightforward integration of the BlinkID Verify SDK using the provided UX in Jetpack Compose to verify a document and display the results.

SDK integration

Adding BlinkID Verify SDK dependency

The BlinkID Verify library is available on Microblink maven repository.

In your project root add Microblink maven repository to repositories list:

repositories {
    // ... other repositories
    maven {
        url = uri("https://maven.microblink.com")
    }
}

Add BlinkID Verify as a dependency in module level build.gradle(.kts):

dependencies {
    implementation("com.microblink:blinkid-verify-ux:3.8.0")
}

Launching the document capture session and obtaining the results

1. A valid license key is required to initialize the document capture process. You can request a free trial license key, after you register, at Microblink Developer Hub.. License is bound to the application ID of your app, so please ensure you enter the correct application ID when asked.

2. You first need to initialize the SDK and obtain the BlinkIdVerifySdk instance:

val maybeInstance = BlinkIdVerifySdk.initializeSdk(
    BlinkIdVerifySdkSettings(
        context = context,
        licenseKey = <your_license_key>,
    )
)
when {
    maybeInstance.isSuccess -> {
        val sdkInstance = maybeInstance.getOrNull()
        // use the SDK instance
    }

    maybeInstance.isFailure -> {
        val exception = maybeInstance.exceptionOrNull()
        Log.e(TAG, "Initialization failed", exception)
    }
}

BlinkIdVerifySdk.initializeSdk is a suspend function which should be called from a coroutine.

3. Use CameraScanningScreen composable to launch document capture UX and obtain results:

CameraScanningScreen(
    sdkInstance,
    verifyUiSettings = VerifyUiSettings(),
    captureSessionSettings = CaptureSessionSettings(),
    onCaptureSuccess = { captureResult ->
        // captureResult is BlinkIdVerifyCaptureResult
    },
    onCaptureCanceled = {
        // user canceled the capture
    }
)

Document capture session result

After the document capture session is finished the SDK returns an object of type BlinkIdVerifyCaptureResult. The object contains images of the front and back sides of the document. Additionally, if the barcode is present on the document, the camera frame containing a visible barcode will also be available.

BlinkIdVerifyCaptureResult.toBlinkIdVerifyRequest helper method should be used to prepare BlinkIdVerifyRequest for the verification API call described in the following section.

Launching the document verification API call and obtaining the results

1. You need to create a BlinkIdVerifyRequest by using BlinkIdVerifyCaptureResult:

val blinkIdVerifyRequest = captureResult.toBlinkIdVerifyRequest(
    BlinkIdVerifyProcessingRequestOptions(),
    BlinkIdVerifyProcessingUseCase()
)

Ensure that the CaptureSessionSettings used for capturing document images match the settings used for BlinkIdVerifyRequest.

2. You also need to create a BlinkIdVerifyClient for the document verification service providing your API token.

val client = BlinkIdVerifyClient(
    BlinkIdVerifyServiceSettings(
        // if using self hosted solution, set appropriate base URL
        verificationServiceBaseUrl = "https://usc1.verify.microblink.com/api/v2/docver",
        token = "your_API_token",
    )
)

If you don't already have the API token, contact us at help.microblink.com.

3. Finally use val response = client.verify(blinkIdVerifyRequest) to send the request and fetch the response that will contain either an error reason or the results of the verification process:

CoroutineScope(IO).launch {
    when (val response = client.verify(blinkIdVerifyRequest)) {
        is Response.Error -> {
            // check `response.errorReason` to check why the request failed
        }
        is Response.Success -> {
            // check `response.endpointResponse` for final result
        }
    }
}

Document verification results

The final result from the document verification service is of type BlinkIdVerifyEndpointResponse and it contains both extraction and verification results.

Device requirements

Android version

BlinkID Verify SDK requires Android API level 24 or newer.

Camera

To perform successful scans, the camera preview resolution must be at least 1080p. Note that the camera preview resolution is not the same as the video recording resolution.

Processor architecture

BlinkID Verify SDK is distributed with ARMv7 and ARM64 native library binaries.

BlinkID Verify is a native library written in C++ and available for multiple platforms. Because of this, BlinkID Verify cannot work on devices with obscure hardware architectures. We have compiled SDK's native code only for the most popular Android ABIs.

If you are combining BlinkID Verify library with other libraries that contain native code in your application, make sure to match the architectures of all native libraries. For example, if the third-party library has only ARMv7 version, you must use exactly ARMv7 version of BlinkID Verify with that library, but not ARM64. Using different architectures will crash your app at the initialization step because JVM will try to load all its native dependencies in the same preferred architecture and fail with UnsatisfiedLinkError.

To avoid this issue and ensure that only architectures supported by the BlinkID Verify library are packaged in the final application, add the following statement to your android/defaultConfig block inside build.gradle.kts:

android {
    ...
    defaultConfig {
        ...
        ndk {
            // Tells Gradle to package the following ABIs into your application
            abiFilters += listOf("armeabi-v7a", "arm64-v8a")
        }
    }
}

Pre-bundling the SDK resources into your app

If you want to reduce the SDK startup time and network traffic, you have option to pre-bundle the SDK resources as assets into your application. All required resources are located in libs/resources/assets/microblink/blinkidverify folder. You can bundle it to your application by including the mentioned folder to application's assets. Copy mentioned libs/resources/assets/microblink directory to src/main/assets folder of your application module (or appropriate folder for desired app flavor).

Use BlinkIdVerifySdkSettings to set the following options when instantiating the SDK:

BlinkIdVerifySdkSettings(
    context = context,
    licenseKey = "your_license_key",
    // disable resource download
    downloadResources = false,
    // define path if you are not using a default one: "microblink/blinkidverify"
    // resourceLocalFolder = "path_within_app_assets"
)

Customizing the look and the UX

Simple customizations

You can use basic customization options in our default CameraScanningScreen composable:

CameraScanningScreen(
    sdkInstance,
    // ui settings options
    verifyUiSettings = VerifyUiSettings(
        typography = yourTypography,
        colorScheme = yourColorScheme,
        reticleColors = youReticleColors,
        verifySdkStrings = yourVerifySdkStrings,
        showOnboardingDialog = true, // or false
        showHelpButton = true // or false
    ),
    captureSessionSettings = CaptureSessionSettings(),
    onCaptureSuccess = { captureResult ->
        // result is BlinkIdVerifyCaptureResult
    },
    onCaptureCanceled = {
        // user canceled the capture
    }
)

For a complete reference on available customization options, see VerifyUiSettings API docs.

Advanced customizations

Implementing scanning Composable

It is possible to use completely custom UI elements by implementing your own Composable.

Create your implementation of scanning ViewModel (which must be a subclass of our CameraViewModel) to handle UX events that come from our SDK:

class YourBlinkIdVerifyScanningUxViewModel(
    blinkIdVerifySdkInstance: BlinkIdVerifySdk,
    captureSessionSettings: CaptureSessionSettings
) : CameraViewModel() {

    val imageAnalyzer = BlinkIdVerifyAnalyzer(
        verifySdk = blinkIdVerifySdkInstance,
        captureSessionSettings = captureSessionSettings,
        scanningDoneHandler = object : ScanningDoneHandler {
            override fun onScanningFinished(result: BlinkIdVerifyCaptureResult) {
                // TODO use capture result
            }

            override fun onScanningCancelled() {
                // user cancelled the scanning
            }
        },
        uxEventHandler = object : ScanningUxEventHandler {
            override fun onUxEvents(events: List<ScanningUxEvent>) {
                // handle scanning UX events to update UI state
                for (event in events) {
                    when (event) {
                        is ScanningUxEvent.ScanningDone -> {
                            // TODO
                        }

                        is ScanningUxEvent.DocumentNotFound -> {
                            // TODO
                        }

                        is ScanningUxEvent.DocumentNotFullyVisible -> {
                            // TODO
                        }

                        is ScanningUxEvent.DocumentTooClose -> {
                            // TODO
                        }
                        // TODO ... handle other events, when must be exhaustive, omitted for brevity
                    }
                }
            }
        }
    )
    
    override fun analyzeImage(image: ImageProxy) {
        // image has to be closed after processing
        image.use {
            imageAnalyzer?.analyze(it)
        }
    }

     override fun onCleared() {
        super.onCleared()
        // cancel and close image analyzer when view model is cleared
        imageAnalyzer.cancel()
        imageAnalyzer.close()
    }
}

Implement your camera scanning screen Composable by using our CameraScreen Composable which is responsible for camera management:

@Composable
fun YourCameraScanningScreen(
    viewModel: YourBlinkIdVerifyScanningUxViewModel
    //... other required parameters for your UI
) {
    // ...
    CameraScreen(
        cameraViewModel = viewModel,
    ) {
        // TODO your camera overlay Compose content
    }

}

Modifying our blinkid-verify-ux library source code

For larger control over the UX, you can use the open-source blinkid-verify-ux library and perform certain modifications. Only the source files that specifically allow for modification by the license header can be modified.

To do so, you can include the source code of our library directly in your application. It is located in libs/sources/blinkid-verify-ux module.

Please keep in mind that we will regularly make changes and update the source code with each release.

Changing default strings and localization

You can modify strings and add another language. For more information on how localization works in Android, check out the official Android documentation.

Defining your own string resources for UI elements

You can define string resources that will be used instead of predefined ones by using the custom VerifySdkStrings while creating the VerifyUiSettings.

Completely custom UX (advanced)

When using the low-level API, you are responsible for preparing the input image stream (or static images) for analysis as well as building a completely custom UX from scratch based on the image-by-image feedback from the SDK.

Low-level API gives you more flexibility with the cost of a significantly larger integration effort. For example, if you need a camera, you will be responsible for camera management and displaying real-time user guidance.

Adding BlinkID Verify Core SDK dependency for low-level API

For low-level API integration, only BlinkID Verify SDK core library: blinkid-verify-core is needed. The blinkid-verify-ux is not needed.

In your project root, add Microblink maven repository to the repositories list:

repositories {
    // ... other repositories
    maven {
        url = uri("https://maven.microblink.com")
    }
}

Add blinkid-verify-core library as a dependency in module level build.gradle(.kts):

dependencies {
    implementation("com.microblink:blinkid-verify-core:3.8.0")
}

The BlinkIdVerifySdk and CaptureSession

BlinkIdVerifySdk is a singleton that is main entry point to the BlinkID Vreify SDK. It manages the global state of the SDK. This involves managing the main processing, unlocking the SDK, ensuring that licence check is up-to-date, downloading resources, and performing all necessary synchronization for the processing operations.

Once you obtain an instance of the BlinkIdVerifySdk class after the SDK initialization is completed, you can use it to start a document capture session.

CaptureSession is the main object that accepts images and camera frames, processes them and returns frame-by-frame results, and final result when it becomes available.

Analyzing the stream of images

1. First initialize the SDK to obtain BlinkIdVerifySdk instance by calling BlinkIdVerifySdk.initializeSdk suspend function from a Coroutine:

val maybeInstance = BlinkIdVerifySdk.initializeSdk(
    BlinkIdVerifySdkSettings(
        context = context,
        licenseKey = <your_license_key>,
    )
)
when {
    maybeInstance.isSuccess -> {
        val sdkInstance = maybeInstance.getOrNull()
        // use the SDK instance
    }

    maybeInstance.isFailure -> {
        val exception = maybeInstance.exceptionOrNull()
        Log.e(TAG, "Initialization failed", exception)
    }
}

2. Create CaptureSession by calling suspend function BlinkIdVerifySdk.createScanningSession(CaptureSessionSettings)

val captureSession = blinkIdVerifySdk.createScanningSession(CaptureSessionSettings(
    // use CapturePolicy.Video to analyze stream of images, if you have few 
    // images (e.g. from gallery) use CapturePolicy.Photo
    capturePolicy = CapturePolicy.Video,
    // update other options if required
))

3. To process each image (camera frame) that comes to the recognition, call the suspend function CaptureSession.process(InputImage): ProcessResult

val processResult = captureSession.process(inputImage)

There are helper methods for creating InputImage from android.media.Image, androidx.camera.core.ImageProxy and standard Android Bitmap.

Processing of the single frame returns ProcessResult which contains:

• Detailed analysis of the frame, including various detection statuses and potential issues that should be used for frame-by-frame UX updates.
• Completeness status of the overall process.

You should keep calling the process function until the result completeness indicates that the result is complete, but you could have custom logic for cancellation and timeouts.

Obtaining capture results

If after analysis of some image completeness status of ProcessResult indicates that document capture is complete, only then you should get the final result from the CaptureSession:

if (processResult.resultCompleteness.isComplete()) {
    val captureResult = session.getResult()
    // do something with the final result
}

You will get BlinkIdVerifyCaptureResult with document images.

After scanning is completed, it is important to terminate the scanning session

To terminate the scanning session, ensure that ScanningSession.close() is called.

If you are finished with the SDK processing, terminate the SDK to free up resources by invoking BlinkIdVerifySdk.close() on the SDK instance.

Troubleshooting

Integration difficulties

In case of problems with SDK integration, make sure that you have followed integration instructions and device requirements. If you're still having problems, please contact us at help.microblink.com describing your problem and provide the following information:

• high-resolution scan/photo of the item that you are trying to read
• information about device that you are using - we need the exact model name of the device. You can obtain that information with any app like this one
• please stress that you are reporting a problem related to the Android version of BlinkID Verify SDK

Additional info

BlinkID Verify SDK size

We recommend that you distribute your app using App Bundle. This will defer APK generation to Google Play, allowing it to generate minimal APK for each specific device that downloads your app, including only required processor architecture support.

Here is the SDK size, calculated for supported ABIs:

ABI	Download size	Install size
armeabi-v7a	3.38 MB	5.09 MB
arm64-v8a	3.51 MB	6.09 MB

SDK size is calculated as application size increases when BlinkID Verify SDK is added, with all its dependencies included.

BlinkID Verify SDK size with bundled resources

API documentation

You can find the BlinkID Verify SDK KDoc documentation here.

Contact

For any other questions, feel free to contact us at help.microblink.com.