Plugin Response

Response States

SUCCESS: Process finished successfully

CAPTURED_IMAGES: Images captured by SDK are returned during runtime

EXIT: Process terminated by the user with no errors

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

EVENT_LOGS: SDK event logs are returned during runtime

ERROR_LOGS: SDK error logs are returned during runtime

ERROR : Process terminated due to an error in the builder

Note: in the case of ERROR, please review your configurations

Document verification plus - Case Handling

When using VIDVOCRResult.getData(), the returned ocrResult may include a documentVerificationPlus object. 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:
/// - All decisions below are only example handling logic.
/// - You can customize the actions based on your own business needs.
/// - Functions such as `requestRecapture`, `showError`, `showRetryDialog()`
///   are examples and must be implemented on your side.

var flags = result.data?.ocrResult?.documentVerificationPlus;

if (flags) {

    // --------------------- GENERIC VALIDATION RESULTS --------------------- //

    // Document failed main validation rules
    if (flags.frontDataValidity === false || flags.backDataValidity === false) {
        showRetryDialog(
            "Document failed validation checks.",
            "Please try again.",
            function () { startOCR(); } // Example retry handler
        );
    }

    // Greyscale / black & white detection
    else if (flags.isFrontGreyscale === true || flags.isBackGreyscale === true) {
        requestRecapture("Document appears to be black & white.");
    }

    // Expired document case
    else if (flags.isExpired === true) {
        showRetryDialog(
            "OCR",
            "Expired ID — please try again with a valid National ID.",
            function () { startOCR(); }
        );
    }

    // Fields require validation review
    else if (flags.reviewRequired && flags.reviewRequired.length > 0) {
        showError("Some fields require manual review.");
    }

    // --------------------- FIELD-LEVEL VALIDATION CASES --------------------- //

    var review = flags.reviewRequired || [];

    if (review.includes("serial_number")) {
        showRetryDialog(
            "OCR",
            "Serial number is incorrect — please try again.",
            function () { startOCR(); }
        );
    }

    if (review.includes("front_nid") || review.includes("back_nid")) {
        requestRecapture("NID Mismatch");
    }

    if (review.includes("date_of_birth")) showError("Date of birth could not be verified.");
    if (review.includes("street")) showError("Street field is empty or invalid.");
    if (review.includes("police_station")) showError("Police station requires review.");
    if (review.includes("governorate")) showError("Governorate field could not be verified.");
    if (review.includes("birth_governorate")) showError("Birth governorate requires validation.");
    if (review.includes("expiry_date")) showError("Expiry date is invalid or unreadable.");
    if (review.includes("release_date")) showError("Release date failed verification.");

    else {
        // DEFAULT CASE -> Document accepted successfully
    }
}

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
var fraud = result?.data?.ocrResult?.advancedConfidence;

// Parent Evaluation
if (fraud?.fraudDetectionZone === 1) showWarning("Suspicious — review manually"); // Replace with custom handling
if (fraud?.fraudDetectionZone === 2) requestRecapture("Possible fraud — re-capture recommended"); // Developer replaces with custom retry logic

// Sub-Flags (if you require a custom message for each case)
if (fraud?.faceFraudZone > 0) showError("Face region shows manipulation indicators"); // Replace with custom handling
if (fraud?.frontImageManipulationZone > 0) showError("Document surface may be edited"); // Replace with custom handling

Primary Response Object

nameValuePairs

Note: All SDK responses are returned in JSON format

Note: This is the first-level object

ocrResult Object Body

Note: This is the second-level object that contains all third-level objects

• 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>

• serialNumber <string>

• frontNid <string>

• backNid <string>

• frontDataValidity <boolean>

• backDataValidity <boolean>

• frontConfidence <int>

• backConfidence <int>

• isRootOfTrustCompatible <boolean>

• transactionIdFront <string>

• transactionIdBack <string>

• combinationID <string>

captures <sub-object>

• nationalIdFront <base64-string>

• nationalIdBack <base64-string>

Note: captures object contains the latest images used for the OCR service

hmacDataList <list>

• serviceID: ocr

• hmacDigest <string>

• rawResponse <string>

The raw response in hmacDataList should be mapped to the result object as per the HMAC Validation Documentation

capturedImages Object Body

• nationalIDLabel <string>

• nationalIdImage <base64-string>

Note: capturedImages is a list of objects that contains all images captured throughout the experience

log Object Body

• date <string>

• key<string>

• screen <string>

• timestamp <string>

• type <string>

• sessionID <string>

errors Object Body

• code<string>

• message<base64-string>

• date <string>

• screen <string>

• timestamp <string>

• type <string>

• sessionID <string>

Note: events and errors objects are only returned if enable_logging is set to true from the plugin configuration

State Responses

SUCCESS

• nameValuePairs <object>

  • state <string>

  • ocrResult <sub-object>

CAPTURED_IMAGES

• nameValuePairs <object>

  • state <string>

  • capturedImage <object>

EXIT

• nameValuePairs <object>

  • state <string>

  • ocrResult <object>

  • step <string>

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

FAILURE

• nameValuePairs <object>

  • state <string>

  • ocrResult <object>

  • errorCode <int>

  • errorMessage <string>

ERROR

• nameValuePairs <object>

  • state <string>

  • errorCode <int>

  • errorMessage <string>

EVENT_LOGS

• nameValuePairs <object>

  • state <string>

  • log <object>

ERROR_LOGS

• state <string>

• log <object>