A. Performing an Authentication

This guide explains how to initiate the Entrupy item authentication process using the iOS SDK, including providing item metadata and handling the results from the capture flow.

Pre-requisite

Ensure SDK User Authorization is complete and the user has a valid token before proceeding.

1. Optional: Fetching Configuration

The SDK requires certain configuration data from Entrupy's servers to operate. While the SDK can fetch this implicitly when you start a capture, doing so can add a few seconds of overhead to the first capture initiation.

To optimize, you can optionally pre-fetch this configuration, for example, when your relevant view controller appears (viewDidAppear).

// Swift
import EntrupySDK

// Ensure your class conforms to EntrupyConfigDelegate
// class YourViewController: UIViewController, EntrupyConfigDelegate { ... }

func prefetchSDKConfiguration() {
    guard EntrupyApp.sharedInstance().isAuthorizationValid() else {
        print("User not authorized. Cannot fetch config.")
        // Handle re-authorization if needed
        return
    }

    EntrupyApp.sharedInstance().configDelegate = self // 'self' is your EntrupyConfigDelegate

    // Use .ConfigTypeProduction for release builds.
    // .ConfigTypeDebug provides a shorter capture workflow for development (results in 'Invalid').
    EntrupyApp.sharedInstance().fetchConfigurationType(EntrupyConfigType.ConfigTypeProduction)
}

Delegate Implementation:

// Swift
// extension YourViewController: EntrupyConfigDelegate {

    func didFetchConfigurationSuccessfully() {
        print("Entrupy SDK configuration fetched successfully.")
        // Now ready to start capture flow with minimal delay.
    }

    func didFetchConfigurationFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String) {
        print("Failed to fetch Entrupy SDK configuration. Error: \(localizedDescription)")
        // Handle error: inform user, log, etc.
        // The SDK might still work but the first capture may be slower.
    }
// }

2. Preparing Item Metadata

Before starting the capture flow, prepare the item details to pass to the SDK. Always include:

• product_category (String, required): One of luxury, sneakers, apparel.

2.1 Luxury

• Required fields
  • brand (String, e.g., "Louis Vuitton")
• Optional fields
  • customer_item_id (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
  • material (String, e.g., "Monogram Canvas", "Damier Ebene Canvas")
• Example

// Swift
func luxuryItemMetadata() -> [String: Any] {
    return [
        "product_category": "luxury",
        "brand": "Louis Vuitton",
        "material": "Monogram Canvas",
        "customer_item_id": "LV-NEVERFULL-MM-001"
    ]
}

2.2 Sneakers

• Required fields
  • brand (String, e.g., "Nike")
  • style_name (String, e.g., "Air Jordan 1 Retro High OG SP")
• Optional fields
  • customer_item_id (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
  • us_size (String): e.g., "8", "8.5", "8.5Y"
  • upc (String): The item's Universal Product Code.
  • style_code (String): e.g., "555088-134"
• Example

// Swift
func sneakersItemMetadata() -> [String: Any] {
    return [
        "product_category": "sneakers",
        "brand": "Nike",
        "style_name": "Air Jordan 1 Retro High OG SP",
        "us_size": "9.5",
        "style_code": "DO7097-100",
        "customer_item_id": "AJ1-DO7097-100-9_5"
    ]
}

2.3 Apparel

• Required fields
  • brand (String, e.g., "BAPE")
  • item_type (String, e.g., "Outerwear", "Tops", "Bottoms", "Dresses")
• Optional fields
  • customer_item_id (String): Unique identifier from your system (max 256 chars). Highly recommended for tracking.
• Example

// Swift
func apparelItemMetadata() -> [String: Any] {
    return [
        "product_category": "apparel",
        "brand": "BAPE",
        "item_type": "Outerwear",
        "customer_item_id": "GU-TEE-CLASSIC-BLK-M"
    ]
}

Brand and Item Information

Accurate item information is important for the authentication process. Consult Entrupy documentation or support for a list of supported brand identifiers and naming conventions if unsure.

3. Starting the Capture Flow

To begin an authentication, call the startCapture method. This will present Entrupy's UI modally, guiding the user through the image capture process.

Ensure your class conforms to the EntrupyCaptureDelegate protocol to handle the outcomes. Build the itemMetadata per Step 2, making sure it includes product_category and the required category-specific fields.

// Swift
import EntrupySDK
import UIKit

// Ensure your class conforms to EntrupyCaptureDelegate
// class YourViewController: UIViewController, EntrupyCaptureDelegate { ... }

func initiateEntrupyAuthentication() {
    guard EntrupyApp.sharedInstance().isAuthorizationValid() else {
        print("User not authorized. Please log in first.")
        // Trigger re-authorization flow
        return
    }
    // Build metadata per Step 2, including 'product_category' and required fields for that category
    // Examples:
    // let itemMetadata = luxuryItemMetadata()
    // let itemMetadata = apparelItemMetadata()
    let itemMetadata = sneakersItemMetadata()

    EntrupyApp.sharedInstance().captureDelegate = self // 'self' is your EntrupyCaptureDelegate

    // 'self' here is the UIViewController that will present the capture flow
    EntrupyApp.sharedInstance().startCapture(forItem: itemMetadata, viewController: self)
    print("Entrupy capture flow initiated for item: \(itemMetadata["customer_item_id"] ?? "N/A")")
}

Timeout

Captures not completed by the user within 2 hours will automatically be canceled by the SDK, and the didCaptureTimeout delegate method will be invoked.

4. Handling Capture Delegate Callbacks

Implement the EntrupyCaptureDelegate methods to respond to the different outcomes of the capture process.

// Swift
// extension YourViewController: EntrupyCaptureDelegate {

    // Called when the user successfully submits the item to Entrupy for verification.
    // The `result` dictionary contains information about the submission, including an initial status or ETA.
    // The final authentication outcome (e.g., Authentic, Unidentified) is determined by Entrupy's backend
    // and will typically be communicated asynchronously (e.g., via webhook or by polling).
    func didCaptureCompleteSuccessfully(_ result: [AnyHashable: Any], forItem item: [AnyHashable: Any]) {
        print("Capture complete for item: \(item["customer_item_id"] ?? "N/A")")
        print("Submission result payload: \(result)")

        // Example: Decode the result if it's structured (e.g., EntrupyCaptureResult from v1 legacy)
        // You might need to adapt this based on the actual structure of the 'result' dictionary
        // provided by the current SDK version.
        do {
            let jsonData = try JSONSerialization.data(withJSONObject: result)
            // Assuming a decodable struct like EntrupyCaptureResult exists for the payload:
            // let parsedResult = try JSONDecoder().decode(EntrupyCaptureResult.self, from: jsonData)
            // print("Initial status/ETA: \(parsedResult.status.result.display.header)")

            // TODO: Update UI to inform user (e.g., "Item submitted, awaiting results.")
            // TODO: Store submission identifiers from 'result' to track status with your backend.
        } catch {
            print("Error decoding capture result: \(error)")
        }
    }

    // Called if the user manually cancels the capture workflow.
    func didUserCancelCapture(forItem item: [AnyHashable: Any]) {
        print("User cancelled capture for item: \(item["customer_item_id"] ?? "N/A")")
        // Update UI accordingly (e.g., allow user to restart or dismiss).
    }

    // Called if the capture process times out (e.g., 2 hours of inactivity).
    func didCaptureTimeout(forItem item: [AnyHashable: Any]) {
        print("Capture timed out for item: \(item["customer_item_id"] ?? "N/A")")
        // Inform user and handle appropriately.
    }

    // Called if an error occurs during the item submission process.
    func didCaptureFailWithError(_ errorCode: EntrupyErrorCode, description: String, localizedDescription: String, forItem item: [AnyHashable: Any]) {
        print("Capture failed for item: \(item["customer_item_id"] ?? "N/A"). Error: \(localizedDescription) (Code: \(errorCode))")
        // Handle the error: inform user, log for debugging, retry logic if appropriate.
        // Refer to the Error Code Reference for details on specific error codes.
    }
// }

After the capture is successfully submitted, your application will typically wait for the final authentication result, which is often delivered to your backend via webhooks. After reviewing Handling Background Tasks, the following section Managing Authentication Results will cover how to interpret and display these results within your app.