Parsing Responses in Document Scan SDK for iOS

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.

Note: As part of receiving the response from our SDK, you will need to implement the necessary delegate methods. Each of the below steps occurs within the handleScan(result:DSResult) function. If you are not yet familiar with this, you may want to start with the Initial Integration steps outlined on a separate page.

Step 1: Extract an Image

It is recommends 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 for each use case. The general implementation flow is as follows:

First, determine if images are uncropped.

Copy

var imagesCropped = true
if result.uncroppedImage != nil,
    result.isImageCropped == false {
    imagesCropped = false
}

if result.uncroppedFlashImage != nil,
    result.isFlashImageCropped == false {
    imagesCropped = false
}

Then, check for distance confidence. Confidence scores may differ per use case, so client code may need to be dialed-in as needed.

Copy

if imagesCropped, result.confidence < 0.6,
    result.distanceConfidence < 0.6 {
    // document is not well-centered in the frame
}

If you don’t need to know the quality of the document position, then you can simply check for isImageCropped and confidence.

Copy

if imagesCropped && confidence < 0.6 {
    // Image quality is not good
}

if imagesCropped && 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.