# 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

{% hint style="info" %}
Note: in the case of `ERROR`, please review your configurations
{% endhint %}

### 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 `reviewRequired`to 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**

```swift
/// 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**

<pre class="language-javascript"><code class="lang-javascript">//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

<strong>// Sub-Flags (if you require a custom message for each case)
</strong>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
</code></pre>

### Primary Response Object

`nameValuePairs`&#x20;

{% hint style="info" %}
Note: All SDK responses are returned in JSON format
{% endhint %}

{% hint style="info" %}
Note: This is the first-level object
{% endhint %}

#### `ocrResult` Object Body

{% hint style="info" %}
Note: This is the second-level object that contains all third-level objects
{% endhint %}

* `sessionID` \<string>

<details>

<summary><code>ocrResult</code> &#x3C;sub-object></summary>

* `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>

</details>

<details>

<summary><code>captures</code> &#x3C;sub-object></summary>

* `nationalIdFront` \<base64-string>
* `nationalIdBack` \<base64-string>

</details>

{% hint style="info" %}
Note: `captures` object contains the latest images used for the OCR service
{% endhint %}

<details>

<summary><code>hmacDataList</code> &#x3C;list></summary>

* `serviceID:` ocr
* `hmacDigest` \<string>
* `rawResponse` \<string>

</details>

{% hint style="info" %}
The raw response in `hmacDataList` should be mapped to the result object as per the [HMAC Validation Documentation ](https://valify.gitbook.io/documentation/response-data-validation)
{% endhint %}

#### `capturedImages` Object Body

* `nationalIDLabel` \<string>
* `nationalIdImage` \<base64-string>

{% hint style="info" %}
Note: `capturedImages` is a list of objects that contains all images captured throughout the experience
{% endhint %}

#### `log` Object Body&#x20;

* `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>

{% hint style="info" %}
Note: `events` and `errors` objects are only returned if `enable_logging` is set to true from the plugin configuration
{% endhint %}

### State Responses

<mark style="color:blue;">`SUCCESS`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>&#x20;
  * `ocrResult` \<sub-object>

<mark style="color:blue;">`CAPTURED_IMAGES`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>
  * [`capturedImage` \<object>](#capturedimages-object-body)

<mark style="color:blue;">`EXIT`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>
  * `ocrResult` \<object>
  * `step` \<string>

{% hint style="info" %}
Note: step \<string> identifies the point where the user chose to exit the SDK
{% endhint %}

<mark style="color:red;">`FAILURE`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>
  * `ocrResult` \<object>
  * `errorCode` \<int>
  * `errorMessage` \<string>

<mark style="color:red;">`ERROR`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>
  * `errorCode` \<int>
  * `errorMessage` \<string>

<mark style="color:blue;">`EVENT_LOGS`</mark>

* `nameValuePairs` \<object>
  * `state` \<string>
  * `log` \<object>

<mark style="color:blue;">`ERROR_LOGS`</mark>

* `state` \<string>
* `log` \<object>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://valify.gitbook.io/valify-ios-sdk-documentation/document-capture/cordova-plugin/plugin-response.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.