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 object that describes the item being authenticated. Always include:

• brandId (String, required): The brand identifier (e.g., "nike", "gucci")
• productCategory (ProductCategory, required): One of Luxury, Sneakers, or Apparel

1.1 Luxury

• Required fields
  • brandId (String, e.g., "gucci", "louis_vuitton")
• Optional fields
  • customerItemId (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
• Example

import com.entrupy.sdk.model.ConfigMetadata
import com.entrupy.sdk.model.ProductCategory

val luxuryMetadata = ConfigMetadata(
    brandId = "gucci",
    productCategory = ProductCategory.Luxury,
    customerItemId = "LV-NEVERFULL-MM-001"
)

1.2 Sneakers

• Required fields
  • brandId (String, e.g., "nike", "adidas")
• Optional fields
  • customerItemId (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
• Example

import com.entrupy.sdk.model.ConfigMetadata
import com.entrupy.sdk.model.ProductCategory

val sneakersMetadata = ConfigMetadata(
    brandId = "nike",
    productCategory = ProductCategory.Sneakers,
    customerItemId = "AJ1-DO7097-100-9_5"
)

1.3 Apparel

• Required fields
  • brandId (String, e.g., "bape")
• Optional fields
  • customerItemId (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
• Example

import com.entrupy.sdk.model.ConfigMetadata
import com.entrupy.sdk.model.ProductCategory

val apparelMetadata = ConfigMetadata(
    brandId = "bape",
    productCategory = ProductCategory.Apparel,
    customerItemId = "BAPE-TEE-CLASSIC-BLK-M"
)

📌 Tip: The customerItemId is strongly recommended for inventory tracking and duplicate prevention. Contact Entrupy for supported brand identifiers if unsure.

2. Starting the Capture Flow

2.1 Simple Capture (Default Configuration)

📌 Recommended: Always supply ConfigMetadata when calling startCapture(). See Section 2.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, category, 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()
}

2.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.ProductCategory

val entrupyApp = EntrupyApp.sharedInstance()

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

val metadata = ConfigMetadata(
    brandId = "nike",
    productCategory = ProductCategory.Sneakers,
    customerItemId = "INTERNAL_SKU_12345"
)

entrupyApp.startCapture(
    configMetadata = metadata,
    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)
        }
    }
)

2.3 Capture with Metadata Only (No Callback)

You can also provide metadata without a callback:

val metadata = ConfigMetadata(
    brandId = "gucci",
    productCategory = ProductCategory.Luxury
)

entrupyApp.startCapture(configMetadata = metadata)

3. Handling Capture Results

The CaptureCallback interface provides two methods:

Method	Description
onCaptureStarted()	Called when the capture UI launches successfully
onCaptureError(errorCode, description)	Called when capture fails to start

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. 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.ProductCategory

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

                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 with brand, category, and item ID
5	Call startCapture(...) to launch Entrupy's guided UI
6	Handle CaptureCallback events
7	Wait for final results via webhook or backend query