Skip to main content

Capture Flow UI Guide

The Entrupy iOS SDK's Capture Flow provides a guided, user-friendly interface for submitting items for authentication. It simplifies the process of capturing necessary images and metadata, aiming for successful submissions on the first attempt.

Overview​

The Capture Flow is a modal UI experience that your application presents to the user. Key characteristics include:

  • Guided Image Acquisition: Step-by-step instructions tailored to the item's brand and type, ensuring all required views are captured.
  • Real-time Feedback: The SDK may incorporate client-side machine learning to provide instant feedback on image quality (e.g., blur detection, glare warnings, framing assistance). (Specific "smart capture" enhancements will be detailed as they become generally available.)
  • Dynamic Image Requests: The system might request additional images during the capture session if more information is needed for a comprehensive assessment.
  • Metadata Collection: Facilitates the input of necessary item metadata.

Upon successful completion, the Capture Flow submits the data to Entrupy for processing. An optional Results Screen can be displayed immediately, or your application can transition to a custom UI, often using the Detail View Controller to track the authentication status.

Initiating the Capture Flow​

To start the Capture Flow, your application invokes the startCapture method on the EntrupyApp shared instance. This typically happens in response to a user action, like tapping an "Authenticate Item" button.

Prerequisites:​

  1. Valid Authorization Token: Ensure the user is logged into the SDK and has a valid authorization token. See Session and Token Lifecycle Management.
  2. Presenting View Controller: You need a reference to the view controller that will present the modal Capture Flow UI.
  3. Item Metadata: Prepare a dictionary containing metadata for the item being authenticated.

Method Invocation:​

// Swift

// 1. Prepare Item Metadata
// 'brand' and 'style_name' are mandatory.
// Other fields like 'us_size', 'upc', 'style_code', and 'customer_item_id' are optional but recommended.
let itemMetadata: [String: Any] = [
    "brand": "Nike", // Mandatory
    "style_name": "Air Jordan 1 Retro High OG SP", // Mandatory
    "us_size": "9.5",
    "upc": "00195244532483",
    "style_code": "DO7097-100",
    "customer_item_id": "SKU-INTERNAL-12345" // Your internal identifier for the item (max 256 chars)
]

// 2. Check Authorization and Present
if EntrupyApp.sharedInstance().isAuthorizationValid() {
    // 3. Assign the Capture Delegate
    EntrupyApp.sharedInstance().captureDelegate = self // 'self' must conform to EntrupyCaptureDelegate

    // 4. Start the Capture Flow
    EntrupyApp.sharedInstance().startCapture(forItem: itemMetadata, viewController: self)
} else {
    // Handle invalid or expired token: initiate re-authorization
    print("Authorization token is invalid. Please log in again.")
}

Item Metadata Parameters:​

  • brand (String): Mandatory. The item's brand (e.g., "Nike", "Louis Vuitton"). This influences the capture guidance.
  • style_name (String): Mandatory. The item's full style name (e.g., "Air Jordan 1 Retro High White University Blue Black").
  • us_size (String, Optional): The item's US Size (e.g., "8", "8.5", "8.5Y").
  • upc (String, Optional): The item's Universal Product Code.
  • style_code (String, Optional): The item's style code or style ID (e.g., "555088-134").
  • customer_item_id (String, Optional): A unique identifier your system uses for the item (max length 256 characters). Highly recommended for tracking.

Refer to knowledge_base/product_snapshot/current_product_state.md for more context on the importance of item metadata fields.

The Capture Process UI​

Once startCapture is called, the SDK modally presents a series of screens guiding the user:

  1. Category/Type Refinement (If Applicable): For some brands with diverse product lines, the user might be asked to select a more specific item category (e.g., handbag, wallet, shoe type). This helps tailor the image capture sequence.
  2. Guided Image Capture: The core of the flow. The user is prompted to take specific photos (e.g., front view, back view, logo details, hardware, date codes, internal tags) according to on-screen instructions and visual guides.
    • The SDK utilizes the device camera.
    • Real-time assistance (smart capture features) may be provided to check for common issues like blur, glare, or poor framing. If an issue is detected, the user is typically prompted to retake the photo.
  3. Additional Images (If Prompted): Based on the initial set of images, the system might immediately request additional, specific photos to ensure a complete data package for robust authentication.
  4. Review and Submission: The user may have an opportunity to review the captured images before confirming submission. Once confirmed, the SDK uploads the images and metadata to Entrupy.

Captures not completed within 2 hours will automatically be aborted, and the didCaptureTimeout delegate method will be invoked.

EntrupyCaptureDelegate Callbacks​

To respond to events and outcomes from the Capture Flow, your presenting view controller (or a dedicated delegate object) must implement the EntrupyCaptureDelegate protocol.

// Swift
extension YourViewController: EntrupyCaptureDelegate {

    // Invoked when the user successfully submits the item to Entrupy for verification.
    // The `result` dictionary contains the initial authentication data, often including an Entrupy ID and status.
    // This `result` dictionary is decodable with the `EntrupyCaptureResult` struct.
    func didCaptureCompleteSuccessfully(_ result: [AnyHashable : Any], forItem item: [AnyHashable : Any]) {
        do {
            let decoder = JSONDecoder()
            let jsonData = try JSONSerialization.data(withJSONObject: result)
            let parsedResult = try decoder.decode(EntrupyCaptureResult.self, from: jsonData)

            print("Capture complete! Entrupy ID: \(parsedResult.item.entrupyId ?? "N/A")")
            print("Initial item status: \(parsedResult.status.result.display.header)")

            // Store the Entrupy ID and other relevant data.
            // You can now transition to the Detail View or show an ETA.
        } catch {
            print("Error decoding capture result: \(error)")
            // Handle decoding error
        }
    }

    // Invoked if the user quits the capture workflow without submitting the item.
    func didUserCancelCapture(forItem item: [AnyHashable : Any]) {
        print("User cancelled capture for item: \(item["customer_item_id"] ?? "N/A")")
        // Handle cancellation, e.g., dismiss loading indicators, allow user to try again.
    }

    // Invoked if the capture timed out (default 2 hours).
    func didCaptureTimeout(forItem item: [AnyHashable : Any]) {
        print("Capture timed out for item: \(item["customer_item_id"] ?? "N/A")")
        // Inform the user about the timeout.
    }

    // Invoked if the item submission fails for reasons other than timeout or cancellation.
    func didCaptureFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String, forItem item: [AnyHashable : Any]) {
        print("Capture failed for item: \(item["customer_item_id"] ?? "N/A"). Error: \(localizedDescription)")
        // Handle the error. Refer to `error-code-reference.md` for details.
        showAlert(title: "Submission Error", message: localizedDescription)
    }
}

(The EntrupyCaptureResult struct mentioned above is based on the structure implied in sdk-v1-legacy.md (Section 9). Ensure you use the exact structure provided by the current SDK version.)

Fetching Configuration (Optional Optimization)​

To potentially reduce latency when starting a capture or search, you can optionally pre-fetch SDK configuration. This is not mandatory, as the SDK will fetch it implicitly if needed, but doing so earlier (e.g., in viewDidAppear) can provide a slight performance benefit.

// Swift
// In your ViewController, e.g., in viewDidAppear
if EntrupyApp.sharedInstance().isAuthorizationValid() {
    EntrupyApp.sharedInstance().configDelegate = self // Conform to EntrupyConfigDelegate

    // Use .ConfigTypeProduction for release builds.
    // .ConfigTypeDebug provides a shorter workflow for development (results will be Invalid).
    EntrupyApp.sharedInstance().fetchConfigurationType(EntrupyConfigType.ConfigTypeProduction)
}

EntrupyConfigDelegate Implementation​

// Swift
extension YourViewController: EntrupyConfigDelegate {
    func didFetchConfigurationSuccessfully() {
        print("Entrupy configuration fetched successfully.")
    }

    func didFetchConfigurationFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String) {
        print("Failed to fetch Entrupy configuration. Error: \(localizedDescription)")
        // Handle error, though the SDK can often recover or fetch config implicitly later.
    }
}

Smart Capture Features​

The SDK aims to incorporate "smart capture" features to enhance image quality and submission success rates. These may include:

  • Real-time image analysis: Checks for focus, lighting, and framing issues.
  • Automatic prompts for improvement: Guides users to correct detected issues on the spot.

These features are designed to create a smoother user experience and increase the accuracy of authentications.

Next Steps​