Capture Flow UI

The Entrupy Android SDK's Capture Flow provides a guided, user-friendly interface for authentication, Fingerprint Register, and Fingerprint Compare. 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 uses on-device AI to provide instant feedback on image quality, including blur detection, glare warnings, and framing assistance.
• 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.

1. Initiating the Capture Flow

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

1.1 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. ConfigMetadata: Prepare a ConfigMetadata object containing metadata for the item being authenticated.

1.2 Method Invocation:

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.CaptureCallback
import com.entrupy.sdk.model.METADATA_KEY_BRAND
import com.entrupy.sdk.model.METADATA_KEY_ITEM_TYPE
import com.entrupy.sdk.model.METADATA_KEY_CUSTOMER_ITEM_ID
import com.entrupy.sdk.model.configMetadataOf

// 1. Prepare ConfigMetadata
val configMetadata = configMetadataOf(
    METADATA_KEY_BRAND to "Nike",
    METADATA_KEY_ITEM_TYPE to "Sneakers",
    METADATA_KEY_CUSTOMER_ITEM_ID to "SKU-INTERNAL-12345" // Your internal identifier (max 256 chars)
)

// 2. Check Authorization and Present
val entrupyApp = EntrupyApp.sharedInstance()

if (entrupyApp.isAuthorizationValid()) {
    // 3. Start the Capture Flow (callback is optional)
    entrupyApp.startCapture(
        configMetadata = configMetadata,
        callback = object : CaptureCallback {
            override fun onCaptureStarted() {
                Log.d("Capture", "Capture flow launched successfully")
            }
            
            override fun onCaptureError(errorCode: Int, description: String) {
                Log.e("Capture", "Capture failed to start: $description")
                showAlert("Error", description)
            }
        }
    )
} else {
    // Handle invalid or expired token: initiate re-authorization
    Log.e("Capture", "Authorization token is invalid. Please log in again.")
}

1.3 ConfigMetadata Parameters:

Authentication

• METADATA_KEY_BRAND (String, required): The item's brand identifier in Title Case (e.g., "Nike", "Louis Vuitton"). This influences the capture guidance.
• METADATA_KEY_ITEM_TYPE (String, required): The item type in Title Case (e.g., "Sneakers", "Handbag", "Outerwear").
• METADATA_KEY_CUSTOMER_ITEM_ID (String, required): A unique identifier your system uses for the item (max 256 characters). Used for tracking and duplicate prevention.
• METADATA_KEY_STYLE_NAME, METADATA_KEY_STYLE_CODE, METADATA_KEY_US_SIZE, METADATA_KEY_MATERIAL (String, optional): Additional metadata for more specific configuration.

See Performing an Authentication — How the SDK Evaluates Metadata for the rules the SDK uses to match these parameters to a capture flow.

Fingerprint

Fingerprint capture supports registering an item's physical characteristics and comparing an item with a previously registered fingerprint. Both flows use METADATA_KEY_CAPTURE_WORKFLOW.

Register

Parameter	Requirement	Behavior
METADATA_KEY_CAPTURE_WORKFLOW	Required	Set to CAPTURE_WORKFLOW_FINGERPRINT_REGISTER.
METADATA_KEY_ITEM_TYPE	Optional	Opens the matching Register flow. When omitted, the SDK opens the item menu filtered to Register flows.
METADATA_KEY_CUSTOMER_ITEM_ID	Optional	Submits the caller-owned value through the hidden SKU field. When omitted, the field remains blank.

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.model.CAPTURE_WORKFLOW_FINGERPRINT_REGISTER
import com.entrupy.sdk.model.METADATA_KEY_CAPTURE_WORKFLOW
import com.entrupy.sdk.model.METADATA_KEY_CUSTOMER_ITEM_ID
import com.entrupy.sdk.model.METADATA_KEY_ITEM_TYPE

val registerMetadata = mapOf<String, Any?>(
    METADATA_KEY_CAPTURE_WORKFLOW to CAPTURE_WORKFLOW_FINGERPRINT_REGISTER,
    METADATA_KEY_ITEM_TYPE to "Bags",
    METADATA_KEY_CUSTOMER_ITEM_ID to "ITEM-001"
)

EntrupyApp.sharedInstance().startCapture(configMetadata = registerMetadata)

Compare

Parameter	Requirement	Behavior
METADATA_KEY_CAPTURE_WORKFLOW	Required	Set to CAPTURE_WORKFLOW_FINGERPRINT_COMPARE. Compare fails if neither supported identifier is supplied.
METADATA_KEY_CUSTOMER_ITEM_ID	Conditionally required	Searches for the caller-owned item before capture. Exactly one registered item must match.
METADATA_KEY_ENTRUPY_ID	Conditionally required	Looks up a single registered fingerprint by Entrupy ID before capture. Takes precedence over Customer Item ID.

import com.entrupy.sdk.model.CAPTURE_WORKFLOW_FINGERPRINT_COMPARE
import com.entrupy.sdk.model.METADATA_KEY_CAPTURE_WORKFLOW
import com.entrupy.sdk.model.METADATA_KEY_CUSTOMER_ITEM_ID
import com.entrupy.sdk.model.METADATA_KEY_ENTRUPY_ID

// Resolve Compare using your application's item identifier.
val compareByCustomerItemId = mapOf<String, Any?>(
    METADATA_KEY_CAPTURE_WORKFLOW to CAPTURE_WORKFLOW_FINGERPRINT_COMPARE,
    METADATA_KEY_CUSTOMER_ITEM_ID to "ITEM-001"
)

// Or resolve Compare directly using an Entrupy ID.
val directCompareMetadata = mapOf<String, Any?>(
    METADATA_KEY_CAPTURE_WORKFLOW to CAPTURE_WORKFLOW_FINGERPRINT_COMPARE,
    METADATA_KEY_ENTRUPY_ID to "ENT-FP-001"
)

Provide either METADATA_KEY_ENTRUPY_ID or METADATA_KEY_CUSTOMER_ITEM_ID. If both are supplied, the Entrupy ID takes precedence. Compare opens region capture only after the SDK resolves exactly one registered item.

The SDK reports these terminal fingerprint preparation errors through CaptureCallback.onCaptureError() and closes the capture activity without showing its generic error screen:

Condition	Error
No identifier supplied for Compare	MISSING_METADATA_KEY (2004)
No item matches either identifier	SEARCH_ITEM_NOT_FOUND (1002)
Multiple items match a Customer Item ID	SEARCH_ITEM_FOUND (1001)
Account is not permitted to use the workflow	WORKFLOW_NOT_PERMITTED (2005)

Always provide a CaptureCallback for fingerprint flows so your application can handle these errors.

See Fingerprint Metadata for complete entry-mode, fallback, and error-handling details.

2. The Capture Process UI

Once startCapture is called, the SDK launches a full-screen activity guiding the user:

1. Item Selection (If Applicable): For authentication, missing or unmatched brand and item type metadata opens the most specific available selection menu (see Section 4). For Fingerprint Register, omitting the item type opens a menu filtered to Register flows; an unmatched item type first shows fallback guidance.
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.
   • Smart capture features 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.

3. CaptureCallback Callbacks

To respond to events and outcomes from the Capture Flow, implement the CaptureCallback interface. The callback is optional.

import com.entrupy.sdk.listeners.CaptureCallback

class YourActivity : AppCompatActivity(), CaptureCallback {

    // Invoked when the capture flow launches successfully
    override fun onCaptureStarted() {
        Log.d("Capture", "Capture flow started")
    }

    // Invoked if the capture flow fails to start
    override fun onCaptureError(errorCode: Int, description: String) {
        Log.e("Capture", "Capture failed: $description (Code: $errorCode)")
        showAlert("Error", description)
    }

    // Invoked when the capture exceeds the timeout duration (default: 2 hours)
    override fun onCaptureTimeout() {
        Log.w("Capture", "Capture timed out")
        showAlert("Timeout", "The capture session has expired.")
    }
}

note

The CaptureCallback reports capture launch and preparation events, including direct Fingerprint Compare lookup errors. Final authentication and fingerprint results are delivered to your backend. Your app should display a pending state or use the Detail View to track status.

4. Parameter Evaluation Rules

For authentication captures, the values you supply for METADATA_KEY_BRAND and METADATA_KEY_ITEM_TYPE are matched deterministically against the supported capture flows for your account:

Provided Metadata	SDK Behavior
Brand matches and item type matches a supported capture flow	The SDK takes the user directly into that capture flow.
Brand matches, item type does not match (or is missing)	The SDK shows an item type selection menu scoped to the provided brand. The brand-level menu is not shown.
Brand does not match (regardless of item type)	The SDK shows the full brand menu, allowing the user to navigate and pick what they want to capture.

To skip menus entirely, supply both a recognized brand and a recognized item type. Otherwise, the SDK falls back to the most specific menu it can show given the parameters provided. Contact Entrupy for the list of supported brand and item type values.

5. Smart Capture Features

The SDK includes smart capture features to enhance image quality and submission success rates:

• 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

• Understand the optional Results Screen UI for immediate post-capture feedback.
• Learn how to display ongoing progress and final results using the Detail View Controller.