Repository files navigation

TheBlinkID Android SDK is a comprehensive solution for implementing secure document scanning and extraction. It offers powerful capabilities for extracting data from a wide range of identification documents.

• 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
• Using SDK throughBlinkIdScanActivity
• Completely custom UX (advanced)
  • TheBlinkIdSdk andBlinkIdScanningSession
• Troubleshooting
• Additional info
  • BlinkID SDK size
  • API documentation
  • Contact

1. Open Android Studio.
2. InQuick Start dialog chooseOpen project.
3. InFile dialog selectBlinkID folder.
4. Wait for the project to load. If Android Studio asks you to reload the project on startup, selectYes.

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

TheBlinkID library is available on Maven Central repository.

In your project root, addmavenCentral() repository to the repositories list, if not already present:

repositories {    // ... other repositories    mavenCentral()}

AddBlinkID as a dependency in module levelbuild.gradle(.kts):

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

1. A valid license key is required to initialize the document capture process. You can request a free trial license key, after you register, atMicroblink Developer Hub.. License is bound to theapplication 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 theBlinkIdSdk instance:

val maybeInstance=BlinkIdSdk.initializeSdk(BlinkIdSdkSettings(        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)    }}

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

3. UseBlinkIdCameraScanningScreen composable to the scanning UX and obtain results:

BlinkIdCameraScanningScreen(    sdkInstance,    uiSettings=UiSettings(),    sessionSettings=BlinkIdSessionSettings(),    onScanningSuccess= { scanningResult->// scanningResult is BlinkIdScanningResult    },    onScanningCanceled= {// user canceled the scanning    })

After the document scanning session is finished the SDK returns an object of typeBlinkIdScanningResult.The object contains extraction process details, document class info, and extraction results. Results are separated into general results and section results.General results are a combined set from each entry with the individual data points taken from the most reliable data source (Barcode > MRZ > Visual).

Section results are separated by document side and by data source (Barcode, MRZ, Visual). Each of these individual data sources are available if present on the document (and allowed through scanning settings).

BlinkID SDK requires Android API level24 or newer.

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

BlinkID SDK is distributed withARMv7 andARM64 native library binaries.

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

If you are combiningBlinkID 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 ofBlinkID 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 withUnsatisfiedLinkError.

To avoid this issue and ensure that only architectures supported by theBlinkID library are packaged in the final application, add the following statement to yourandroid/defaultConfig block insidebuild.gradle.kts:

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

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 inlibs/resources/assets/microblink/blinkid folder. You can bundle it to your application by including the mentioned folder to application's assets. Copy mentionedlibs/resources/assets/microblink directory tosrc/main/assets folder of your application module (or appropriate folder for desired app flavor).

UseBlinkIdSdkSettings to set the following options when instantiating the SDK:

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

You can use basic customization options in our defaultBlinkIdCameraScanningScreen composable:

BlinkIdCameraScanningScreen(    sdkInstance,// ui settings options    uiSettings=UiSettings(        typography= yourTypography,        colorScheme= yourColorScheme,        uiColors= youReticleColors,        sdkStrings= yourSdkStrings,        showOnboardingDialog=true,// or false        showHelpButton=true// or false    ),    sessionSettings=BlinkIdSessionSettings(),    onScanningSuccess= { scanningResult->// result is BlinkIdScanningResult    },    onScanningCanceled= {// user canceled the scanning    })

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

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 ourCameraViewModel) to handle UX events that come from our SDK:

classYourBlinkIdScanningUxViewModel(blinkIdSdkInstance:BlinkIdSdk,sessionSettings:ScanningSessionSettings) : CameraViewModel() {val imageAnalyzer=BlinkIdAnalyzer(        blinkIdSdk= blinkIdSdkInstance,        sessionSettings= sessionSettings,        scanningDoneHandler=object:BlinkIdScanningDoneHandler {overridefunonScanningFinished(result:BlinkIdScanningResult) {// TODO use scanning result            }overridefunonScanningCancelled() {// user cancelled the scanning            }overridefunonError(error:ErrorReason) {// handle scanning errors            }        },        uxEventHandler=object:ScanningUxEventHandler {overridefunonUxEvents(events:List<ScanningUxEvent>) {// handle scanning UX events to update UI statefor (eventin events) {when (event) {isScanningUxEvent.ScanningDone-> {// TODO                        }isScanningUxEvent.DocumentNotFound-> {// TODO                        }isScanningUxEvent.DocumentNotFullyVisible-> {// TODO                        }isScanningUxEvent.DocumentTooClose-> {// TODO                        }isBlinkIdDocumentLocatedLocation-> {// TODO                        }isDocumentImageAnalysisResult-> {// TODO                        }// TODO ... handle other events, when must be exhaustive, omitted for brevity                                        }                }            }        }    )overridefunanalyzeImage(image:ImageProxy) {// image has to be closed after processing        image.use {            imageAnalyzer?.analyze(it)        }    }overridefunonCleared() {super.onCleared()// cancel and close image analyzer when view model is cleared        imageAnalyzer.cancel()        imageAnalyzer.close()    }}

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

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

For larger control over the UX, you can use the open-sourceblinkid-ux andmicroblink-ux libraries 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.They are located inlibs/sources/blinkid-ux andlibs/sources/microblink-ux modules.

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

Strings used within built-in activities and UX can be localized to any language.

We have already prepared strings for several languages which you can use out of the box. You can also modify those strings, or you can add your own language. Languages natively supported by our SDK are the following:Arabic,Chinese simplified,Chinese traditional,Croatian,Czech,Dutch,Filipino,French,German,Hebrew,Hungarian,Indonesian,Italian,Malay,Portugese,Romanian,Serbian,Slovak,Slovenian,Spanish,Thai, andVietnamese.

The language is automatically adapted to the user's OS language settings. Additionally, to force a specific language, you have to enable it from the code.

BlinkID can easily be translated to other languages. Theres folder inmicroblink-ux has foldervalues which containsstrings_core.xml - this file contains english strings. In order to make e.g. croatian translation, create a foldervalues-hr in your project and put the copy ofstrings_core.xml inside it. Then, open that file and translate the strings from English into Croatian.

To modify an existing string, the best approach would be to:

1. Choose a language you want to modify. For example Croatian ('hr').
2. Findstrings_core.xml in folderres/values-hr
3. Choose a string key which you want to change. For example:<string name="mb_close">Close</string>
4. In your project create a filestrings_core.xml in the folderres/values-hr, if it doesn't already exist
5. Create an entry in the file with the value for the string which you want. For example:<string name="mb_back">Zatvori</string>
6. Repeat for all the string you wish to change

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

You can define string resources that will be used instead of predefined ones by using the customSdkStrings while creating theUiSettings.

The simplest way of using BlinkID SDK is through our integrated activity.This eliminates the need for Compose integration and allows for quick and easy access to results. By using this integration method customization is reduced, although many UI elements can still be customized.

Activity is accessed throughrememberLauncherForActivityResult by usingMbBlinkIdScan contract.

val blinkIdLauncher= rememberLauncherForActivityResult(        contract=MbBlinkIdScan(),        onResult= { activityResult->if (activityResult.status==BlinkIdScanActivityResultStatus.DocumentScanned) {// use activityResult.result (BlinkIdScanningResult)            }        }    )

When launching the contract,BlinkIdScanActivitySettings need to be defined. These settings include basic SDK information such as license key and additional settings for customizing the scanning experience.

    blinkIdLauncher.launch(BlinkIdScanActivitySettings(BlinkIdSdkSettings(                licenseKey=<your_license_key>            ),BlinkIdSessionSettings(                scanningSettings=ScanningSettings(// define additional settings here                )            )        )    )

BlinkIdScanActivitySettings contain the following:

data classBlinkIdScanActivitySettings(valblinkIdSdkSettings:BlinkIdSdkSettings,valscanningSessionSettings:BlinkIdSessionSettings =BlinkIdSessionSettings(),valuxSettings:BlinkIdUxSettings =BlinkIdUxSettings(),valscanActivityUiColors:BlinkIdActivityColors? =null,valscanActivityUiStrings:SdkStrings =SdkStrings.Default,valshowOnboardingDialog:Boolean =DefaultShowOnboardingDialog,valshowHelpButton:Boolean =DefaultShowHelpButton,valenableEdgeToEdge:Boolean =true,valdeleteCachedAssetsAfterUse:Boolean =false    )

Most customizations regarding the UI are handled in the same way as with the Composable component. The only difference is a limitation in customizingTypography andColors.

Currently,Typography cannot be customized through an activity.

WhileColors are fully customizable, the client needs to make sure thatDark andLight themes follow the current system state. In the Compose implementation, this is handled directly by the SDK.

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.

For low-level API integration, onlyBlinkID SDK core library:blinkid-core is needed.Bothblinkid-ux andmicroblink-ux are not needed.

In your project root, addmavenCentral() repository to the repositories list, if not already present:

repositories {    // ... other repositories    mavenCentral()}

Addblinkid-core library as a dependency in module levelbuild.gradle(.kts):

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

BlinkIdSdk is a singleton that is main entry point to theBlinkID 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 theBlinkIdSdk class after the SDK initialization is completed, you can use it to start a document capture session.

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

1. First initialize the SDK to obtainBlinkIdSdk instance by callingBlinkIdSdk.initializeSdk suspend function from a Coroutine:

val maybeInstance=BlinkIdSdk.initializeSdk(BlinkIdSdkSettings(        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. CreateBlinkIdScanningSession by calling suspend functionBlinkIdSdk.createScanningSession(BlinkIdSessionSettings)

val scanningSession= blinkIdSdk.createScanningSession(BlinkIdSessionSettings(// use InputImageSource.Video to analyze stream of images, if you have few// images (e.g. from gallery) use InputImageSource.Photo    inputImageSource=InputImageSource.Video,// update other options if required))

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

val processResult= scanningSesionSession.process(inputImage)

There are helper methods for creatingInputImage fromandroid.media.Image,androidx.camera.core.ImageProxy and standard Android Bitmap.

Processing of the single frame returnsProcessResult which contains:

• Detailed analysis of the input image, 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.

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

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

You will getBlinkIdScanningResult with extraction results.

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

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

If you are finished with the SDK processing, terminate the SDK to free up resources by invokingBlinkIdSdk.closeAndDeleteCachedAssets() on the SDK instance. If you just wish to close the SDK but may need to use it and the future, you can eliminate the need for re-downloading the resources by callingBlinkId.close().

In case of problems with SDK integration, make sure that you have followedintegration instructions anddevice requirements. If you're still having problems, please contact us athelp.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 likethis one
• please stress that you are reporting a problem related to the Android version ofBlinkID SDK

We recommend that you distribute your app usingApp 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:

SDK size is calculated as application size increases whenBlinkID SDK is added, with all its dependencies included.

You can find the BlinkID SDKKDoc documentationhere.

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