Parsing Responses in Document Scan SDK for Android
This SDK is provided to help you build the ID Proofing workflow in your applications. The primary role of this SDK is to ensure the best quality image capture for government-issued identity cards (Driver's License, Passport book, or Passport card).
For best results, we have a 3-step approach. This helps your consumers capture the image and ensures the image quality is pristine to assist the server side with decisioning.
Step 1: Extract an Image
It is recommended that only uncropped images are submitted to our APIs. If the SDK cannot detect the document edges, then our server will most likely have the same problem.
Depending on which images you decide to use, you must inform the API whether the image is cropped via the AutoCrop header.
The images that are returned within the DSResult object are as follows:
| Property Name | Description | Image Cropped? | Autocrop Value |
|---|---|---|---|
| croppedImage | The cropped image. | True | False |
| croppedFlashImage | The cropped image with flash. | True | False |
| uncroppedImage | The uncropped image. | False | True |
| uncroppedFlashImage | The uncropped image with flash. | Flase | True |
| Image | The best non-flash image chosen by the SDK (cropped or not). | Dynamic | Dynamic |
| flashImage | The best image with flash chosen by the SDK (cropped or not). | Dynamic | Dynamic |
Step 2: Unpack DSResult
A DSResult contains a detailed capture analysis. Combined with the image data, these fields allow you to decide which images, if any, are valid for processing.
| Property Name | Description |
|---|---|
| isImageCropped | Indicates if the SDK was able to crop the non-flash image. |
| isFlashImageCropped | Indicates if the SDK was able to crop the flash image. |
| confidence |
Indicates the SDK’s confidence level on the image quality. Value ranges between 0 and 1. It is recommended to have a response of at least 0.60. |
| captureAnalysis.distanceConfidence |
Indicates the SDK’s confidence level on the distance between the camera and the document. Value ranges between 0 and 1. It is recommended to have a response of at least 0.60. |
| captureAnalysis.faceDetected | Indicates if the SDK could see a human face in the document image. |
Step 3: Decisioning
It is up to consuming applications to determine the best decisioning model as it pertains to each use case, but general implementation typically follows the same outline.
First, determine if images are uncropped using the following code:
if (result.uncroppedImage != nil) {
// uncropped image present
}
if (result.uncroppedFlashImage != nil) {
// uncropped flash image present
}Then, check for distance confidence. Confidence scores may differ depending on the use case, so edit the following code as needed:
if ((result.confidence < 0.6) &&
(result.captureAnalysis.distanceConfidence < 0.6)) {
// document is not well-centered in the frame
}If you don't need to know the quality of the document position, use this code instead:
if (result.confidence < 0.6) {
// Image quality is not good
}
if (result.confidence >= 0.6) {
// Image quality is good
}Tracking State in a Capture Workflow
To keep track of how many times a user goes through the license or passport scan process, there needs to be a mechanism that tracks the state of the workflow. Once a user exceeds the specified amount of retries, the workflow sends the last image taken. For example, our SDK might not be able to read newer barcodes, but the server can. By eventually sending an image to the server, there is a higher probability of success.
Create or modify a state machine to replicate the flow described in the figure below. Use a variable, such as rescanCount, to keep track of the number of times a user has to retake an image due to processing failure. If the user exceeds the maximum number of retries (totalAttempts), the image should be sent to the server for an attempt at processing. If the user manually selects to retake the picture, it does not count toward the rescanCount limit.
