Skip to main content

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.

The getFlagDetailsForResult SDK method allows you 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.

func fetchFlagDetails(for entrupyID: String) {
    // The exact method signature might vary (e.g., using a delegate pattern or a modern completion handler)
    // This example assumes a completion handler as shown in sdk-v1-legacy.md.
    EntrupyApp.sharedInstance().getFlagDetailsForResult(withEntrupyID: entrupyID) { [weak self] result, error in
        guard let self = self else { return }

        if let error = error {
            let nsError = error as NSError
            print("Error fetching flag details for \(entrupyID): \(nsError.localizedDescription) (Code: \(nsError.code))")
            // Handle error: show alert to user, log, etc.
            // Refer to Error Code Reference for specific error codes.
            return
        }

        if let resultData = result {
            do {
                let jsonData = try JSONSerialization.data(withJSONObject: resultData)
                // Assuming a decodable struct like EntrupyCaptureResultStatusFlag exists for the payload
                // (as per sdk-v1-legacy.md). Adapt if the SDK provides a different structure.
                // struct EntrupyCaptureResultStatusFlag: Decodable {
                //     enum FlagStatus: String, Decodable { case none, flagged, resolved }
                //     let id: FlagStatus?
                //     let is_flaggable: Bool?
                // }
                // let parsedResult = try JSONDecoder().decode(EntrupyCaptureResultStatusFlag.self, from: jsonData)

                // ---- Conceptual interpretation based on legacy structure ----
                // Replace with actual parsing based on current SDK's EntrupyCaptureResultStatusFlag structure
                let flagStatusId = (resultData["id"] as? String) ?? "none" // e.g., "none", "flagged", "resolved"
                let isFlaggable = (resultData["is_flaggable"] as? Bool) ?? false
                // ---- End conceptual interpretation ----

                print("Flag details for \(entrupyID): Status=\(flagStatusId), Flaggable=\(isFlaggable)")

                if (flagStatusId == "none" || flagStatusId == "resolved") && isFlaggable {
                    // Show UI option to "Flag Result"
                    print("Action: Allow user to flag this result.")
                } else if flagStatusId == "flagged" {
                    // Show UI option to "Clear Flag" or "View Flag Status"
                    // Clearing a flag might only be allowed for the original flagger or based on permissions.
                    print("Action: Allow user to clear this flag (if permitted), or view status.")
                } else {
                    // Item is not flaggable, or in a state that doesn't allow action.
                    // Do not show flag/clear flag options.
                    print("Action: No flag actions available for the user.")
                }

            } catch {
                print("Error decoding flag details result for \(entrupyID): \(error)")
            }
        } else {
            print("No result or error returned from getFlagDetailsForResult for \(entrupyID)")
        }
    }
}

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.