SDK Response

SDK Listener

Use the following code snippet to receive SDK callbacks

VIDVOCRListener vidvOcrListener= new VIDVOCRListener() {
            @Override
            public void onOCRResult(VIDVOCRResponse response) {
                if (response instanceof Success) {
                   
                     
                     
                     //an example code to use the response in your app : 
                     String firstName = ((Success) response).getData().getOcrResult().getFirstName();
                     //firstName variable will hold the first name of the scanned National ID
                     
                     
                     // Add your own code
                     
                     
                } else if (response instanceof CapturedImages) {
                
               
                         // Add your own code  
                                       
                } else if (response instanceof UserExit) {
                
                      // Add your own code
                
                } else if (response instanceof ServiceFailure) {
                
                        // Add your own code
                
                } else if (response instanceof BuilderError) {
                
                      // Add your own code
                
                }
            }
        };

Document verification plus - Case Handling

When using VIDVOCRResult.getData(), the returned ocrResult may include a documentVerificationPlusobject. This object contains validation flags and quality signals that help you determine whether the document should be accepted, reviewed, recaptured, or rejected.

---

Fields Returned Under documentVerificationPlus

Field	Type	Meaning
frontDataValidity	boolean	Overall validity of the front side based on greyscale flags + invalid fields list
backDataValidity	boolean	Overall validity of the back side based on greyscale flags + invalid fields list
isFrontGreyscale	boolean	Indicates whether the front side is greyscale
isBackGreyscale	boolean	Indicates whether the back side is greyscale
expired	boolean	Whether the document is recognized as expired
reviewRequired	List<String>	Fields that require attention (e.g. Nid, gender, expirydate…)

---

How to Read These Values

• frontDataValidity and backDataValidity act as parent flags → You can take action directly based on them if you want a simple validation flow.

• For more control, you can check detailed signals:

  • use greyscale flags if you want to reject black-and-white copies

  • use reviewRequiredto apply different logic per field e.g. reject if nid is invalid but allow if gender is inconsistent

This allows fully customizable decision logic depending on your business rules.

Example Handling Logic

//Note that all decisions taken in this code are just an example of how you can handle
//the logic and that you can take the preferred action according to your business needs
val flags = result.data?.ocrResult?.documentVerificationPlus
when {
// --------------------- GENERIC VALIDATION RESULTS --------------------- //

// Quick validation using global parent flags
flags?.frontDataValidity == false || flags?.backDataValidity == false -> {
     AlertDialog(
                onDismissDialog = {showRetryOCRSDKDialog.value = false}, onClick = {
                // start ocr sdk
                }
            }, title = "The document failed validation checks." ,"Retry")
}

// Greyscale document detection
flags?.isFrontGreyscale == true || flags?.isBackGreyscale == true -> {
    requestRecapture("Document appears to be black & white.")  // Developer replaces with custom retry logic
}

// Document is expired
flags?.isExpired == true -> {
    AlertDialog(
                onDismissDialog = {showRetryOCRSDKDialog.value = false}, onClick = {
                // start ocr sdk
                }
            }, title = "OCR", "Expired ID, Please try again with your recent National ID." ,"Retry")
}

 // One or more fields require review
    flags?.reviewRequired.isNotEmpty() == true -> {
        showError("Some fields require manual review.")   // Replace with custom handling
    }


// --------------------- FIELD-LEVEL CASES (HANDLE INDIVIDUALLY) --------------------- //

"serial_number" in flags?.reviewRequired.orEmpty() -> {
    AlertDialog(
                onDismissDialog = {showRetryOCRSDKDialog.value = false}, onClick = {
                // start ocr sdk
                }
            }, title = "OCR", "Serial number is incorrect. Please try again" ,"Retry")}
}

"back_nid" in flags?.reviewRequired.orEmpty() ||
"front_nid" in flags?.reviewRequired.orEmpty() -> {
    requestRecapture("NID Mismatch") // Developer replaces with custom retry logic
}
"date_of_birth" in flags?.reviewRequired.orEmpty() -> showError("Date of birth could not be verified.") // Replace with custom handling
"street" in flags?.reviewRequired.orEmpty() -> showError("Street address is empty.") // Replace with custom handling
"police_station" in flags?.reviewRequired.orEmpty() -> showError("Police station field needs review.") // Replace with custom handling
"governorate" in flags?.reviewRequired.orEmpty() -> showError("Governorate value could not be verified.") // Replace with custom handling
"birth_governorate" in flags?.reviewRequired.orEmpty() -> showError("Birth governorate requires review.") // Replace with custom handling
"expiry_date" in flags?.reviewRequired.orEmpty() -> showError("Expiry date is missing or invalid.") // Replace with custom handling
"release_date" in flags?.reviewRequired.orEmpty() -> showError("Release date did not pass validation.") // Replace with custom handling

else -> {
}
}

Advance confidence - Case Handling

When using VIDVOCRResult.getData(), the returned ocrResult may include a advancedConfidence object. This object contains manipulation flags that help you determine whether the document should be accepted, reviewed, recaptured, or rejected.

---

Fields Returned Under advanceConfidence

Field	Type	Meaning
fraudDetectionZone	int	Parent zone flag → Result of face + image manipulation combined
faceFraudZone	int	Fraud confidence specifically related to face physical tampering
frontImageManipulationZone	int	Indicates signs of front image physical manpulation

Zone Meaning

Value	Color	Meaning
0	Green	No manipulation detected
1	Yellow	Requires human review (suspicious)
2	Red	Strong indicators of fraud / manipulation

---

Example Handling Logic

//Note that all decisions taken in this code are just an example of how you can handle
//the logic and that you can take the preferred action according to your business needs
val fraud = result.data?.ocrResult?.advancedConfidence

// Generic Handling
when (fraud?.fraudDetectionZone) {
    1 -> showWarning("Document may be manipulated — review recommended") // Replace with custom handling
    2 -> requestRecapture("Possible fraud detected — please retry with clear document")
}

// Detailed Handling
when {
    fraud?.faceFraudZone == 1 || fraud?.faceFraudZone == 2 -> 
        showError("Face area appears manipulated")

    fraud?.frontImageManipulationZone == 1 || fraud?.frontImageManipulationZone == 2 -> 
        showError("Front side image shows manipulation traces")

    else -> { /* Accept normally */ }
}

Response Instances

Success : Process finished successfully

CapturedImages: Images captured are returned in real-time

Note: ForCapturedImagesinstance, images are not processed yet

BuilderError : Process terminated due to an error in the builder

Note: Check your configurations

ServiceFailure : Process finished with the user's failure to pass the service requirements

UserExit : Process terminated by the user with no errors

Primary Response Object

VIDVOCRResult

Note: This is the first-level object that contains all the second-level objects. It is present in these type of response and holds data related to the responses, includingSuccess,ServiceFailure, and UserExit.

Here is the attributes of VIDVOCRResultclass that represents the data that could be retrived from the response object VIDVOCRResponse using getData() method that returnsVIDVOCRResultobject like in the example code above showing a use of Success response.

• captures : <Captures>

• documentVerificationResult : <DocumentVerificationResult>

• ocrResult : <VIDVOCRData>

• decryptionKeys : <VIDVDecryptionKeys>

• hmacDataList : <List<HmacData>>

• sessionID : <String>

Object Body

• sessionID <string>

ocrResult <sub-object>

• firstName <string>

• fullName <string>

• religion <string>

• gender <string>

• dateOfBirth <string>

• age <int>

• maritalStatus <string>

• husbandName <string>

• street <string>

• birthGovernorate <string>

• policeStation <string>

• governorate <string>

• profession <string>

• releaseDate <string>

• expiryDate <string>

• expired <boolean> : indicates whether the NID is past its expiry date.

• serialNumber <string>

• frontNid <string>

• backNid <string>

• frontDataValidity <boolean> : data on the front side is valid or not.

• backDataValidity <boolean> : data on the back side is valid or not.

• frontConfidence <int> : indicates if the front of the document is real or fake.

• backConfidence <int> : indicates if the back of the document is real or fake.

• isRootOfTrustCompatible <boolean>

• transactionIdFront <string> : This could be used in face match in liveness sdk.

• transactionIdBack <string>

• combinationID <string>

• documentVerificationPlus <object>

  • frontDataValidity <boolean> : data on the front side is valid or not based on the greyscale flags & the review required list.

  • backDataValidity <boolean> : data on the back side is valid or not based on the greyscale flags & the review required list.

  • isFrontGreyscale<boolean>

  • backConfidence <int>

  • isBackGreyscale<boolean>

  • expired <boolean>

  • reviewRequiredArrayList<string> : an ArrayList of the names of fields that is invalid.

• advancedConfidence <object>

  • fraudDetectionZone <int>

  • fraudDetectionDetails <object>

    • faceFraudZone <int>

    • faceFraudConfidence <float>

    • frontImageManipulationZone <int>

    • frontImageManipulationConfidence <float>

documentVerificationResult <sub-object>

• success <boolean>

captures <sub-object>

• nationalIdFront <base64-string>

• nationalIdBack <base64-string>

hmacDataList <list>

• serviceID : ocr

• hmacDigest <string>

• rawResponse <string>

decryptionKeys <sub-object>

• nationalIdFrontRequestKey [UInt8]

• nationalIdBackRequestKey [UInt8]

• combineResponseKey [UInt8]

The raw response in hmacDataList should be mapped to the result object as per the HMAC validation documentation

Instance Responses

Success

• VIDVOCRResult <object>

CapturedImages

CapturedImageData <object>

• nationalIDLabel <string>

• nationalIdImage <base64-string>

UserExit

• VIDVOCRResult <object>

• step <string>

Note: step <string> identifies the point where the user chose to exit the SDK

ServiceFailure

• VIDVOCRResult <object>

• code <string>

• message <string>

BuilderError

• code <string>

• message <string>