B. Handling Result Flags

Entrupy provides a flagging mechanism that allows users or integrators to report a potential issue with an authentication result assigned by Entrupy. This system directs the Entrupy support team to review the specific case and resolve it appropriately. Flagging is the preferred method for disputing a result, rather than resubmitting an item, which could incur additional costs.

Purpose of Flags

Flags are typically used when an end-user or the integrating platform believes there might be an error or a need for re-evaluation of an authentication outcome. The ability to allow users to flag via SDK is configurable; for some deployments limiting this function to the platform is a better fit.

1. Getting Flag Details for a Result

Before allowing a user to flag a result, or to display the current flag status, you must fetch the flag details for that specific authentication result using its Entrupy ID.

Use getFlagDetailsForResult(withEntrupyID:completionHandler:) to obtain:

• The current flag status (e.g., none, flagged, resolved).
• Whether the item is currently eligible to be flagged (is_flaggable).

Not all result types are eligible for flagging. It is important to check is_flaggable before attempting to set or clear a flag to avoid errors.

// Swift
import EntrupySDK

// Assume 'entrupyID' is the Entrupy ID of the authentication result in question.
// Ensure your class conforms to a delegate or uses a completion handler
// as provided by the SDK for this asynchronous operation.

// EntrupyCaptureResultStatusFlag is provided by the SDK (PublicModels/EntrupyCaptureResult.swift)

func fetchFlagDetails(for entrupyID: String) {
    EntrupyApp.sharedInstance().getFlagDetailsForResult(withEntrupyID: entrupyID) { result, error in
        if let error = error {
            let nsError = error as NSError
            print("Error fetching flag details for \(entrupyID): \(nsError.localizedDescription) (Code: \(nsError.code))")
            return
        }

        guard let resultData = result else {
            print("No result or error returned from getFlagDetailsForResult for \(entrupyID)")
            return
        }

        do {
            let jsonData = try JSONSerialization.data(withJSONObject: resultData)
            let details = try JSONDecoder().decode(EntrupyCaptureResultStatusFlag.self, from: jsonData)
            let statusId = details.id
            let isFlaggable = details.is_flaggable
            print("Flag details for \(entrupyID): Status=\(statusId.description), Flaggable=\(isFlaggable)")

            switch statusId {
            case .none, .resolved:
                // If status is 'none' or 'resolved' AND is_flaggable is true -> present 'Flag' option
                if isFlaggable {
                    // Show 'Flag' button
                } else {
                    // Hide buttons
                }
            case .flagged:
                // If status is 'flagged' -> present 'Clear Flag' option
                // Show 'Clear Flag' button
                break
            case .other:
                // Hide buttons
                break
            }
        } catch {
            print("Error decoding flag details result for \(entrupyID): \(error)")
        }
    }
}

2. Setting or Clearing a Flag

Once you have determined that an item can be flagged (or a flag can be cleared), use the setFlag SDK method. This method typically takes the Entrupy ID and a boolean parameter (true to set/submit a flag, false to clear/revoke an existing flag).

Ensure your relevant class conforms to the EntrupyFlagDelegate protocol.

// Swift
import EntrupySDK

// Ensure your class conforms to EntrupyFlagDelegate
// class YourViewController: UIViewController, EntrupyFlagDelegate { ... }

func submitOrClearFlag(for entrupyID: String, setFlagValue: Bool) {
    guard EntrupyApp.sharedInstance().isAuthorizationValid() else {
        print("User not authorized. Cannot set flag.")
        // Handle re-authorization
        return
    }

    EntrupyApp.sharedInstance().flagDelegate = self // 'self' is your EntrupyFlagDelegate
    EntrupyApp.sharedInstance().setFlag(setFlagValue, forResultWithEntrupyID: entrupyID)

    if setFlagValue {
        print("Attempting to set flag for result: \(entrupyID)")
    } else {
        print("Attempting to clear flag for result: \(entrupyID)")
    }
}

Delegate Implementation:

// Swift
// extension YourViewController: EntrupyFlagDelegate {

    func didFlagResultSuccessfully(forEntrupyID entrupyID: String, forRequestedFlag flagValue: Bool) {
        let action = flagValue ? "set" : "cleared"
        print("Flag successfully \(action) for Entrupy ID: \(entrupyID)")
        // Update your UI accordingly.
        // Refresh flag details to get the latest status.
        // self.fetchFlagDetails(for: entrupyID)
    }

    func didFlagResultFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String, forEntrupyID entrupyID: String, forRequestedFlag flagValue: Bool) {
        let action = flagValue ? "set" : "clear"
        print("Failed to \(action) flag for Entrupy ID: \(entrupyID). Error: \(localizedDescription) (Code: \(errorCode))")
        // Handle error: inform user, log.
        // Refer to Error Code Reference for specific error codes.
    }
// }

3. Receiving Flag Resolution Notifications (Backend)

While the SDK allows you to initiate and potentially clear flags, the actual review and resolution of a flag (e.g., if Entrupy support changes a result or adds a note) happens on Entrupy's backend.

To be notified of these changes programmatically:

• Webhooks: Your backend server should be configured to receive webhook notifications from the Entrupy API for updates related to flag statuses or result changes.

Refer to the Entrupy API documentation for details on setting up webhooks.

By implementing these flag management features, you provide a valuable feedback loop for users and ensure that authentication results can be reviewed and addressed if concerns arise.