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.

// Kotlin
import com.entrupy.sdk.EntrupySDK

// Assume 'entrupyID' is the Entrupy ID of the authentication result in question.
// Ensure your class implements the appropriate callback interface
// as provided by the SDK for this asynchronous operation.

fun fetchFlagDetails(entrupyID: String) {
    // The exact method signature might vary based on the SDK implementation
    // This example assumes a callback-based approach
    EntrupySDK.getInstance().getFlagDetailsForResult(entrupyID) { result, error ->
        if (error != null) {
            println("Error fetching flag details for $entrupyID: ${error.message} (Code: ${error.code})")
            // Handle error: show alert to user, log, etc.
            // Refer to Error Code Reference for specific error codes.
            return@getFlagDetailsForResult
        }

        result?.let { flagData ->
            try {
                // Assuming a data class like EntrupyCaptureResultStatusFlag exists for the payload
                // Adapt if the SDK provides a different structure.
                // data class EntrupyCaptureResultStatusFlag(
                //     val id: FlagStatus?,
                //     val is_flaggable: Boolean?
                // )
                // enum class FlagStatus { NONE, FLAGGED, RESOLVED }

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

                println("Flag details for $entrupyID: Status=$flagStatusId, Flaggable=$isFlaggable")

                when {
                    (flagStatusId == "none" || flagStatusId == "resolved") && isFlaggable -> {
                        // Show UI option to "Flag Result"
                        println("Action: Allow user to flag this result.")
                    }
                    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.
                        println("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.
                        println("Action: No flag actions available for the user.")
                    }
                }

            } catch (e: Exception) {
                println("Error decoding flag details result for $entrupyID: $e")
            }
        } ?: run {
            println("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 implements the appropriate callback interface.

// Kotlin
import com.entrupy.sdk.EntrupySDK

// Ensure your class implements the appropriate callback interface
// class YourActivity : AppCompatActivity(), EntrupyFlagCallback { ... }

fun submitOrClearFlag(entrupyID: String, setFlagValue: Boolean) {
    if (!EntrupySDK.getInstance().isAuthorizationValid()) {
        println("User not authorized. Cannot set flag.")
        // Handle re-authorization
        return
    }

    EntrupySDK.getInstance().setFlag(entrupyID, setFlagValue, this) // 'this' implements EntrupyFlagCallback

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

Callback Implementation:

// Kotlin
// class YourActivity : AppCompatActivity(), EntrupyFlagCallback {

    override fun onFlagResultSuccess(entrupyID: String, flagValue: Boolean) {
        val action = if (flagValue) "set" else "cleared"
        println("Flag successfully $action for Entrupy ID: $entrupyID")
        // Update your UI accordingly.
        // Refresh flag details to get the latest status.
        // fetchFlagDetails(entrupyID)
    }

    override fun onFlagResultError(errorCode: EntrupyErrorCode, description: String, localizedDescription: String, entrupyID: String, flagValue: Boolean) {
        val action = if (flagValue) "set" else "clear"
        println("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.