A. Performing an Authentication

This guide explains how to start Entrupy's item authentication process using the Android SDK, including how to provide item metadata and handle results via the capture flow.

Pre-requisite

Ensure SDK User Authorization is complete and the user has a valid session before initiating any capture.

1. Preparing Item Metadata

Before starting the capture flow, prepare a ConfigMetadata map that describes the item being authenticated. ConfigMetadata is created using the METADATA_KEY_* constants from com.entrupy.sdk.model.

For authentication captures, the SDK interface is defined by three metadata keys:

• METADATA_KEY_BRAND (String, required): The brand identifier in Title Case (e.g., "Nike", "Gucci").
• 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 from your system (max 256 chars). Used for inventory tracking and duplicate prevention.

1.1 Example

import com.entrupy.sdk.model.ConfigMetadata
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

val sneakerMetadata = configMetadataOf(
    METADATA_KEY_BRAND to "Nike",
    METADATA_KEY_ITEM_TYPE to "Sneakers",
    METADATA_KEY_CUSTOMER_ITEM_ID to "AJ1-DO7097-100-9_5"
)

tip

METADATA_KEY_CUSTOMER_ITEM_ID is required for all authentications. Contact Entrupy for supported brand and item type identifiers if you are unsure which values to provide.

1.2 Optional Metadata Keys

In addition to the required keys above, you may supply any of the following optional keys to further describe the item:

• METADATA_KEY_STYLE_NAME
• METADATA_KEY_STYLE_CODE
• METADATA_KEY_US_SIZE
• METADATA_KEY_MATERIAL

1.3 Metadata Keys Reference

Constant	Type	Description
METADATA_KEY_BRAND	String	Brand identifier in Title Case (e.g., "Nike", "Gucci"). Required.
METADATA_KEY_ITEM_TYPE	String	Item type in Title Case (e.g., "Sneakers", "Handbag"). Required for authentication and direct Fingerprint Register routing. A missing or unknown Register item type opens the Register fallback menu.
METADATA_KEY_CUSTOMER_ITEM_ID	String	Unique identifier from your system (max 256 chars). Required for authentication. For fingerprint flows, this caller-owned value is optional for Register and can identify the registered item for Compare.
METADATA_KEY_CAPTURE_WORKFLOW	String	Fingerprint workflow: fingerprint_register or fingerprint_compare. Required for dedicated fingerprint captures.
METADATA_KEY_ENTRUPY_ID	String	Entrupy authentication ID used to open Fingerprint Compare directly (optional).
METADATA_KEY_STYLE_NAME	String	Style name (optional).
METADATA_KEY_STYLE_CODE	String	Style code (optional).
METADATA_KEY_US_SIZE	String	US size (optional).
METADATA_KEY_MATERIAL	String	Material (optional).
METADATA_KEY_UPC	String	Universal Product Code (optional).
METADATA_KEY_ITEM_ID	String	Item identifier (optional).
METADATA_KEY_MODE_ID	String	Mode identifier (optional).

1.4 ConfigMetadata Helpers

ConfigMetadata is a typealias for Map<String, Any?>. The SDK provides helper functions for creating and reading metadata:

import com.entrupy.sdk.model.configMetadataOf
import com.entrupy.sdk.model.toConfigMetadata
import com.entrupy.sdk.model.getStringOrNull
import com.entrupy.sdk.model.METADATA_KEY_BRAND
import com.entrupy.sdk.model.METADATA_KEY_CUSTOMER_ITEM_ID

// Create metadata using the helper
val sampleMetadata = configMetadataOf(
    METADATA_KEY_BRAND to "Nike",
    METADATA_KEY_CUSTOMER_ITEM_ID to "SKU-12345"
)

// Convert an existing map to ConfigMetadata
val existingMap = mapOf("brand" to "Nike", "customer_item_id" to "SKU-12345")
val configMetadata = existingMap.toConfigMetadata()

// Read a value safely
val brand = sampleMetadata.getStringOrNull(METADATA_KEY_BRAND) // "Nike"
val missing = sampleMetadata.getStringOrNull("nonexistent_key") // null

1.5 Fingerprint Metadata

Fingerprint capture allows you to register an item's physical characteristics for future comparison or compare an item against a previously registered fingerprint. Dedicated fingerprint captures require METADATA_KEY_CAPTURE_WORKFLOW.

1.5.1 Register

Use CAPTURE_WORKFLOW_FINGERPRINT_REGISTER to register an item's fingerprint.

• Required: METADATA_KEY_CAPTURE_WORKFLOW
• Optional:
  • METADATA_KEY_ITEM_TYPE: Opens the matching Register flow directly. If omitted, the SDK opens the item menu filtered to Fingerprint Register. If the value is not recognized, the SDK explains that the item type was not found and allows the user to browse the filtered menu.
  • METADATA_KEY_CUSTOMER_ITEM_ID: If supplied, is submitted through the hidden SKU field. If omitted, that 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 fingerprintRegisterMetadata = 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 = fingerprintRegisterMetadata
)

1.5.2 Compare

Use CAPTURE_WORKFLOW_FINGERPRINT_COMPARE to compare the current item with a previously registered fingerprint. The caller must identify exactly one registered item before the SDK can open region capture:

Metadata	SDK Behavior
Add METADATA_KEY_ENTRUPY_ID	The SDK looks up that Entrupy ID. If found, region capture opens directly.
Add METADATA_KEY_CUSTOMER_ITEM_ID	The SDK searches for a registered fingerprint with that Customer Item ID. Exactly one item must match.
METADATA_KEY_CAPTURE_WORKFLOW only	The SDK closes the capture activity and reports MISSING_METADATA_KEY through CaptureCallback.onCaptureError().

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 the registered fingerprint using your own 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 it directly using an Entrupy ID.
val compareByEntrupyId = mapOf<String, Any?>(
    METADATA_KEY_CAPTURE_WORKFLOW to CAPTURE_WORKFLOW_FINGERPRINT_COMPARE,
    METADATA_KEY_ENTRUPY_ID to "ENT-FP-001"
)

Compare Identifiers

Provide either METADATA_KEY_ENTRUPY_ID or METADATA_KEY_CUSTOMER_ITEM_ID. If both are supplied, the Entrupy ID takes precedence. The SDK trims and uppercases an Entrupy ID before lookup. Your application and backend are responsible for tracking these identifiers and disambiguating Customer Item IDs before starting Compare. If an item was registered without a Customer Item ID, use its Entrupy ID for future comparisons.

Fingerprint preparation failures are returned through CaptureCallback.onCaptureError():

Condition	EntrupyErrorCode
No registered item matches the supplied Entrupy ID or Customer Item ID	SEARCH_ITEM_NOT_FOUND (1002)
Multiple registered items match the supplied Customer Item ID	SEARCH_ITEM_FOUND (1001)
Compare starts without an Entrupy ID or Customer Item ID	MISSING_METADATA_KEY (2004)
The account is not permitted to use the requested fingerprint workflow	WORKFLOW_NOT_PERMITTED (2005)

These terminal errors close the capture activity. See the Error Code Reference for handling guidance.

Fingerprint Error Callback

Always provide a CaptureCallback when starting Fingerprint Register or Compare so your application can handle preparation and permission errors.

2. How the SDK Evaluates Metadata

For authentication captures, the values you supply for METADATA_KEY_BRAND and METADATA_KEY_ITEM_TYPE are matched against the supported capture flows for your account, and the SDK behaves according to a deterministic set of rules.

2.1 Parameter Evaluation Rules

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.

In short: if you want to skip menus entirely, you must 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 you provided.

Recommended

Always supply complete, recognized values for METADATA_KEY_BRAND and METADATA_KEY_ITEM_TYPE when you want a direct, deterministic capture flow with no menu prompts. Contact Entrupy for the list of supported brand and item type values.

3. Starting the Capture Flow

3.1 Simple Capture (Default Configuration)

Recommended

Always supply ConfigMetadata when calling startCapture(). See Section 3.2 for the preferred integration path.

When startCapture() is called without metadata, the SDK uses the first available configuration encountered. This means:

• No filtering by brand, item type, or function
• Non-deterministic configuration selection
• Bypasses customerItemId for inventory tracking

import com.entrupy.sdk.app.EntrupyApp

val entrupyApp = EntrupyApp.sharedInstance()

if (entrupyApp.isAuthorizationValid()) {
    entrupyApp.startCapture()
} else {
    // Re-authorize first
    performUserAuthorization()
}

3.2 Capture with Metadata and Callback

For full control over the capture process, provide ConfigMetadata and a CaptureCallback. The callback parameter is optional.

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.CaptureCallback
import com.entrupy.sdk.model.ConfigMetadata
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

val entrupyApp = EntrupyApp.sharedInstance()

if (!entrupyApp.isAuthorizationValid()) {
    // Re-authorize first
    performUserAuthorization()
    return
}

val captureMetadata = configMetadataOf(
    METADATA_KEY_BRAND to "Nike",
    METADATA_KEY_ITEM_TYPE to "Sneakers",
    METADATA_KEY_CUSTOMER_ITEM_ID to "INTERNAL_SKU_12345"
)

entrupyApp.startCapture(
    configMetadata = captureMetadata,
    callback = object : CaptureCallback {
        override fun onCaptureStarted() {
            Log.d("Entrupy", "Capture UI launched successfully")
        }

        override fun onCaptureError(errorCode: Int, description: String) {
            Log.e("Entrupy", "Capture failed to start: $description (Code: $errorCode)")
            // Handle error appropriately
            showError(description)
        }
    }
)

3.3 Capture with Metadata Only (No Callback)

You can also provide metadata without a callback:

val handbagMetadata = configMetadataOf(
    METADATA_KEY_BRAND to "Gucci",
    METADATA_KEY_ITEM_TYPE to "Handbag",
    METADATA_KEY_CUSTOMER_ITEM_ID to "YOUR_ITEM_ID"
)

entrupyApp.startCapture(configMetadata = handbagMetadata)

4. Handling Capture Results

The CaptureCallback interface provides three methods:

Method	Description
onCaptureStarted()	Called when the capture UI launches successfully
onCaptureError(errorCode, description)	Called when capture fails to start or prepare, including a failed direct Fingerprint Compare lookup
onCaptureTimeout()	Called when the capture exceeds the configured timeout duration (default: 2 hours). This is a default no-op that you can override to handle timeout scenarios.

note

The CaptureCallback reports capture launch and preparation events; it does not deliver the final authentication or fingerprint outcome. Any initial result displayed within the SDK is advisory, not authoritative. For cases where the result requires review, your app should rely on backend mechanisms—such as webhooks, polling, or server-side status checks via the API—to obtain the final, authoritative outcome.

4.1 Configuring Capture Timeout

Use setCaptureTimeoutDuration(seconds: Long) to customize the timeout duration for capture sessions. The default is 2 hours (7200 seconds).

val entrupyApp = EntrupyApp.sharedInstance()
entrupyApp.setCaptureTimeoutDuration(3600) // Set timeout to 1 hour

5. Complete Integration Example

Here's a complete example showing authorization check and capture flow:

import com.entrupy.sdk.app.EntrupyApp
import com.entrupy.sdk.listeners.CaptureCallback
import com.entrupy.sdk.model.ConfigMetadata
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

class CaptureManager {
    private val entrupyApp = EntrupyApp.sharedInstance()
    
    fun startAuthentication(
        brand: String,
        itemType: String,
        customerItemId: String
    ) {
        // Step 1: Check authorization
        if (!entrupyApp.isAuthorizationValid()) {
            // Trigger re-authorization flow
            onAuthorizationRequired()
            return
        }
        
        // Step 2: Prepare metadata
        val metadata = configMetadataOf(
            METADATA_KEY_BRAND to brand,
            METADATA_KEY_ITEM_TYPE to itemType,
            METADATA_KEY_CUSTOMER_ITEM_ID to customerItemId
        )
        
        // Step 3: Start capture
        entrupyApp.startCapture(
            configMetadata = metadata,
            callback = object : CaptureCallback {
                override fun onCaptureStarted() {
                    Log.d("Entrupy", "Capture started for brand: $brand")
                }

                override fun onCaptureError(errorCode: Int, description: String) {
                    handleCaptureError(description)
                }
            }
        )
    }
    
    private fun handleCaptureError(description: String) {
        showErrorToUser(description)
    }
    
    private fun onAuthorizationRequired() {
        // Navigate to authorization flow
    }
    
    private fun showErrorToUser(message: String) {
        // Display error in UI
    }
}

Example Flow Summary

Step	Action
1	Ensure SDK is initialized (EntrupyApp.init() in Application)
2	Authorize the user with a signed request
3	Check authorization with isAuthorizationValid()
4	Create ConfigMetadata map with METADATA_KEY_* constants
5	Call startCapture(...) to launch Entrupy's guided UI
6	Handle CaptureCallback events
7	Wait for final results via webhook or backend query

Next Steps

• B. Handling Background Tasks
• Managing authentication results