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, including brand and item_type.

Method Invocation:​

// Swift

// 1. Prepare Item Metadata (include brand and item_type)
let itemMetadata: [String: Any] = [
    "brand": "Nike",
    "item_type": "Sneakers",
    // Recommended
    "customer_item_id": "SKU-INTERNAL-12345" // 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​

Authentication​

For authentication captures, provide brand and item_type. The SDK uses these values to match the item against the available capture flows configured for your account.

  • Required
    • brand (String): The brand of the item (e.g., "Louis Vuitton", "Nike", "BAPE").
    • item_type (String): The type of item (e.g., "Outerwear", "Tops", "Sneakers", "Bags").
  • Optional fields
    • customer_item_id (String): Unique identifier from your system. Highly recommended for tracking.
    • us_size (String): e.g., "8", "8.5", "8.5Y"
    • style_code (String): e.g., "555088-134"
    • upc (String): The item's Universal Product Code.
Capture Flow Selection Behavior​

When you provide brand and item_type, the SDK evaluates them against the capture flows available to your account:

  • Brand and item type both match a capture flow: the SDK takes the user directly to that capture flow.
  • Only brand matches: the SDK presents the available item type options for that brand.
  • Brand does not match (regardless of item type): the SDK presents the full capture flow menu for the user to select from.

Example

func itemMetadata() -> [String: Any] {
    [
        "brand": "BAPE",
        "item_type": "Outerwear",
        "customer_item_id": "ITEM-001"
    ]
}

Fingerprint​

Fingerprint capture allows you to register an item's physical characteristics for future comparison or compare an item against previously registered fingerprints.

  • Required
    • customer_item_id (String): Identifier from your system
    • brand (String): The brand of the item
    • item_type (String): The type of item
    • capture_workflow (String): Either fingerprint_register or fingerprint_compare
Register​

Use fingerprint_register to capture and register an item's fingerprint. If items with the same customer_item_id were previously registered, the SDK will display them for reference. You can then continue registering the current item as a new fingerprint or cancel.

func fingerprintRegisterMetadata() -> [String: Any] {
    [
        "customer_item_id": "ABC-abc-123445",
        "brand": "Louis Vuitton",
        "item_type": "Bags",
        "capture_workflow": "fingerprint_register"
    ]
}
Compare​

Use fingerprint_compare to compare the current item against previously registered fingerprints. If multiple items with the same customer_item_id were registered, the SDK will display a list to select which one to compare against. You can select a specific registered item or cancel.

func fingerprintCompareMetadata() -> [String: Any] {
    [
        "customer_item_id": "ABC-abc-123445",
        "brand": "Louis Vuitton",
        "item_type": "Bags",
        "capture_workflow": "fingerprint_compare"
    ]
}

See the Core Authentication guide's "Preparing Item Metadata" for details.

The Capture Process UI​

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

  1. Item Selection (If Applicable): If the provided brand and item_type do not uniquely match a single capture flow, the user may be presented with a selection menu to refine their choice. 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)
    }
}

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​