Skip to main content

Programmatic Access to Customer Support Features

The Entrupy iOS SDK provides built-in UI for customer support primarily through the Detail View Controller, which includes features for structured communications and managing flags. However, the SDK also exposes underlying methods that allow for programmatic interaction with these support features if you need to integrate them into a custom UI or workflow.

This guide covers how to programmatically manage result flags and interact with the structured communication system for item-specific support.

Overview​

Programmatic access to support features generally involves:

  • Managing Flags: Checking the flag status of an authentication result, and setting or clearing flags.
  • Structured Communications: Fetching the history of support messages for an item and, if applicable, sending structured responses.
Prioritize SDK UI

Whenever possible, guiding users to the SDK's built-in support interfaces (e.g., within the Detail View Controller) is recommended. These interfaces are maintained by Entrupy and are designed to align with current support workflows and policies.

Managing Result Flags​

Flagging allows users or integrators to report a potential issue with an authentication result, prompting a review by the Entrupy support team.

1. Getting Flag Details​

Before attempting to set or clear a flag, or to display flag-related UI, you should fetch the current flag details for a given result using its entrupy_id.

// Swift
func fetchFlagDetails(for entrupyId: String) {
    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
            // Handle error (e.g., item not found, network issue)
            print("Error fetching flag details for \(entrupyId): \(nsError.localizedDescription) (Code: \(nsError.code))")
            // self.showAlert(title: "Error", message: "Could not fetch flag details: \(nsError.localizedDescription)")
            return
        }

        if let flagResultData = result {
            do {
                let decoder = JSONDecoder()
                let jsonData = try JSONSerialization.data(withJSONObject: flagResultData)
                // Ensure EntrupyCaptureResultStatusFlag struct matches the SDK's definition
                let parsedFlagStatus = try decoder.decode(EntrupyCaptureResultStatusFlag.self, from: jsonData)

                // Update your UI based on the flag status
                if (parsedFlagStatus.id == .none || parsedFlagStatus.id == .resolved) && parsedFlagStatus.is_flaggable {
                    // Show UI to 'Flag Result'
                    print("Item \(entrupyId) can be flagged.")
                } else if parsedFlagStatus.id == .flagged {
                    // Show UI to 'Clear Flag' or 'View Flag Status'
                    print("Item \(entrupyId) is currently flagged.")
                } else {
                    // Item is not flaggable or in a state that doesn't allow flagging/clearing by user
                    print("Item \(entrupyId) is not currently flaggable or flag status is \(parsedFlagStatus.id).")
                }
            } catch {
                print("Error decoding flag details for \(entrupyId): \(error)")
                // self.showAlert(title: "Error", message: "Could not parse flag details.")
            }
        }
    }
}

(The EntrupyCaptureResultStatusFlag struct and its properties like id and is_flaggable are based on Section 11 of sdk-v1-legacy.md. Verify with current SDK.)

2. Setting or Clearing a Flag​

To flag a result or clear an existing flag, use the setFlag method. You'll need the entrupy_id and a boolean indicating whether to flag (true) or clear the flag (false).

Your class must conform to the EntrupyFlagDelegate protocol to handle the outcome.

// Swift
// Ensure your class conforms to EntrupyFlagDelegate
// EntrupyApp.sharedInstance().flagDelegate = self

func updateFlag(for entrupyId: String, shouldBeFlagged: Bool) {
    EntrupyApp.sharedInstance().flagDelegate = self // Assign delegate before calling setFlag
    EntrupyApp.sharedInstance().setFlag(shouldBeFlagged, forResultWithEntrupyID: entrupyId)
}

// MARK: - EntrupyFlagDelegate Implementation
// extension YourViewController: EntrupyFlagDelegate {
//     func didFlagResultSuccessfully(forEntrupyID entrupyID: String, forRequestedFlag flag: Bool) {
//         print("Flag was successfully \(flag ? "set" : "cleared") for item \(entrupyID).")
//         // Update UI accordingly, perhaps re-fetch flag details or session details
//     }
//
//     func didFlagResultFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String, forEntrupyID entrupyID: String, forRequestedFlag flag: Bool) {
//         print("Failed to \(flag ? "set" : "clear") flag for item \(entrupyID). Error: \(localizedDescription)")
//         // Handle error, refer to error-code-reference.md
//         // showAlert(title: "Flag Error", message: localizedDescription)
//     }
// }

Important Notes on Flagging:​

  • Eligibility: Not all results or items may be eligible for flagging. Always check is_flaggable from getFlagDetailsForResult before offering a flagging option.
  • Backend Webhooks: For server-side notifications of flag status changes (e.g., when Entrupy support resolves a flag), configure webhooks via the Entrupy API. Refer to Section 11 of sdk-v1-legacy.md and API documentation.

Structured Communications (Support Messages)​

Programmatic access to the per-item structured communication system allows you to build custom UI for users to interact with Entrupy support regarding specific authentications.

sdk-v1-legacy.md does not explicitly detail SDK methods for programmatic access to support messages (like fetching history or sending structured responses) as shown in the site/docs/mobile-sdks/ios-old/direct-access/customer-support.md stub. The primary documented support interaction in sdk-v1-legacy.md is through flagging.

Conceptual Methods (If SDK supports them):

If the SDK provides direct methods for message handling (verify with actual SDK capabilities), they might look like this:

// Swift - Conceptual Examples (Verify Actual SDK Methods)

let entrupyIdForSupport = "abc123xyz"

// 1. Fetching Support Message History (Conceptual)
/*
EntrupySDK.shared.fetchSupportMessages(entrupyId: entrupyIdForSupport) { result in // Fictional method
    DispatchQueue.main.async {
        switch result {
        case .success(let messages):
            // 'messages' would likely be an array of message objects
            // Each message might have properties like: text, sender, timestamp, type (user/support)
            // Update your custom chat UI with these messages
            messages.forEach { message in
                // print("Message from \(message.sender): \(message.text)")
            }
            print("Support messages fetched for \(entrupyIdForSupport).")
        case .failure(let error):
            print("Failed to load support messages for \(entrupyIdForSupport): \(error.localizedDescription)")
        }
    }
}
*/

// 2. Listing Available Structured Responses (Conceptual)
// The Detail View often allows users to pick from predefined questions or responses.
// A programmatic equivalent might fetch these available choices.
/*
EntrupySDK.shared.getAvailableSupportResponses(entrupyId: entrupyIdForSupport) { result in // Fictional method
    DispatchQueue.main.async {
        switch result {
        case .success(let responseOptions):
            // 'responseOptions' would be an array of structs/objects, each with an ID and display text
            // Populate your UI (e.g., a picker or list) with these options
            responseOptions.forEach { option in
                // print("Available response: \(option.displayText) (ID: \(option.id))")
            }
        case .failure(let error):
            print("Failed to get available support responses for \(entrupyIdForSupport): \(error.localizedDescription)")
        }
    }
}
*/

// 3. Sending a Structured Support Response (Conceptual)
/*
let chosenResponseId = "user_needs_help_with_retake" // Example ID selected by user from available options
EntrupySDK.shared.sendSupportResponse(entrupyId: entrupyIdForSupport, responseId: chosenResponseId) { result in // Fictional method
    DispatchQueue.main.async {
        switch result {
        case .success:
            print("Successfully sent support response '\(chosenResponseId)' for \(entrupyIdForSupport).")
            // Optionally, refresh the message history
        case .failure(let error):
            print("Failed to send support response for \(entrupyIdForSupport): \(error.localizedDescription)")
        }
    }
}
*/
API Parity

The conceptual methods above mirror capabilities often found in backend APIs for support systems. If the iOS SDK offers such programmatic access, its methods and data models should be clearly defined in its official API reference.

Refer to knowledge_base/product_snapshot/current_product_state.md (Section 1.4) for more context on the support model, which emphasizes Entrupy supporting the platform, and authentication support being handled through the SDK's per-item structured communication.

Best Practices​

  • Delegate Assignment: Always ensure the appropriate delegate (e.g., EntrupyFlagDelegate) is set before calling methods that rely on it.
  • Error Handling: Implement thorough error handling for all programmatic calls.
  • UI Updates: Perform all UI updates on the main thread.
  • Contextual Use: Use programmatic access to complement, not necessarily replace, the SDK's built-in UI, especially for complex interactions like guided retakes or detailed support conversations.

By understanding these programmatic access points, you can create a more deeply integrated support experience if your application requires it.

Next Steps​