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.

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.
`METADATA_KEY_CUSTOMER_ITEM_ID`	String	Unique identifier from your system (max 256 chars). Required.
`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

2. How the SDK Evaluates Metadata

The SDK never guesses what the user wants to capture. 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
`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 only reports whether the capture flow started successfully. 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

1. Preparing Item Metadata​

1.1 Example​

1.2 Optional Metadata Keys​

1.3 Metadata Keys Reference​

1.4 ConfigMetadata Helpers​

2. How the SDK Evaluates Metadata​

2.1 Parameter Evaluation Rules​

3. Starting the Capture Flow​

3.1 Simple Capture (Default Configuration)​

3.2 Capture with Metadata and Callback​

3.3 Capture with Metadata Only (No Callback)​

4. Handling Capture Results​

4.1 Configuring Capture Timeout​

5. Complete Integration Example​

Example Flow Summary​

Next Steps​