Skip to main content

Capture Flow UI Guide

The Entrupy Android 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 full-screen activity or fragment 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 EntrupySDK 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. Context: You need a reference to the context that will be used to launch the Capture Flow activity.
  3. Item Metadata: Prepare a map containing metadata for the item being authenticated.

Method Invocation:​

// Kotlin

// 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.
val itemMetadata = mapOf(
    "brand" to "Nike", // Mandatory
    "style_name" to "Air Jordan 1 Retro High OG SP", // Mandatory
    "us_size" to "9.5",
    "upc" to "00195244532483",
    "style_code" to "DO7097-100",
    "customer_item_id" to "SKU-INTERNAL-12345" // Your internal identifier for the item (max 256 chars)
)

// 2. Check Authorization and Present
if (EntrupySDK.getInstance().isAuthorizationValid()) {
    // 3. Assign the Capture Callback
    EntrupySDK.getInstance().setCaptureCallback(this) // 'this' must implement EntrupyCaptureCallback

    // 4. Start the Capture Flow
    EntrupySDK.getInstance().startCapture(this, itemMetadata)
} else {
    // Handle invalid or expired token: initiate re-authorization
    println("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 launches a full-screen activity 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 onCaptureTimeout callback method will be invoked.

EntrupyCaptureCallback Callbacks​

To respond to events and outcomes from the Capture Flow, your activity (or a dedicated callback object) must implement the EntrupyCaptureCallback interface.

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

    // Invoked when the user successfully submits the item to Entrupy for verification.
    // The `result` object contains the initial authentication data, often including an Entrupy ID and status.
    // This `result` object is typically a data class with the `EntrupyCaptureResult` structure.
    override fun onCaptureCompleteSuccessfully(result: EntrupyCaptureResult, item: Map<String, Any>) {
        println("Capture complete! Entrupy ID: ${result.item.entrupyId ?: "N/A"}")
        println("Initial item status: ${result.status.result.display.header}")

        // Store the Entrupy ID and other relevant data.
        // You can now transition to the Detail View or show an ETA.
    }

    // Invoked if the user quits the capture workflow without submitting the item.
    override fun onUserCancelCapture(item: Map<String, Any>) {
        println("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).
    override fun onCaptureTimeout(item: Map<String, Any>) {
        println("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.
    override fun onCaptureFailWithError(errorCode: EntrupyErrorCode, description: String, localizedDescription: String, item: Map<String, Any>) {
        println("Capture failed for item: ${item["customer_item_id"] ?: "N/A"}. Error: $localizedDescription")
        // Handle the error. Refer to `error-code-reference.md` for details.
        showAlert("Submission Error", localizedDescription)
    }
}

(The EntrupyCaptureResult data class mentioned above is based on the structure implied in the SDK documentation. 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 onResume) can provide a slight performance benefit.

// Kotlin
// In your Activity, e.g., in onResume
if (EntrupySDK.getInstance().isAuthorizationValid()) {
    EntrupySDK.getInstance().setConfigCallback(this) // Implement EntrupyConfigCallback

    // Use .CONFIG_TYPE_PRODUCTION for release builds.
    // .CONFIG_TYPE_DEBUG provides a shorter workflow for development (results will be Invalid).
    EntrupySDK.getInstance().fetchConfiguration(EntrupyConfigType.CONFIG_TYPE_PRODUCTION)
}

EntrupyConfigCallback Implementation​

// Kotlin
class YourActivity : AppCompatActivity(), EntrupyConfigCallback {
    override fun onFetchConfigurationSuccess() {
        println("Entrupy configuration fetched successfully.")
    }

    override fun onFetchConfigurationFail(errorCode: EntrupyErrorCode, description: String, localizedDescription: String) {
        println("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​