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.
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
TODO: Assess for Luxury, Apparel
Before starting the capture flow, you need to gather details about the item being authenticated. This information is passed to the SDK.
Key metadata fields include:
brand(String): Mandatory. The item's brand identifier (e.g., "nike", "louis_vuitton").style_name(String): Mandatory. The item's full style name (e.g., "Air Jordan 1 Retro High OG SP").customer_item_id(String): Highly Recommended. A unique identifier for the item from your system (max length 256 characters). This helps you correlate SDK submissions with your own records.
Optional fields:
us_size(String): The item's US Size (e.g., "8", "8.5", "8.5Y").upc(String): The item's Universal Product Code.style_code(String): The item's style code or SKU (e.g., "555088-134").- Other fields as supported by the SDK (refer to
EntrupySDK.ItemDetailsor similar structure if provided by SDK for precise field names).
Example:
// Swift
func getItemMetadata() -> [String: Any] {
let metadata: [String: Any] = [
"brand": "Nike", // From Entrupy's supported brand list
"style_name": "Air Jordan 1 Retro High OG SP",
"customer_item_id": "YOUR_INTERNAL_SKU_12345",
"us_size": "9.5",
"upc": "00195244532483",
"style_code": "DO7097-100"
// Add other relevant key-value pairs based on the item
]
return metadata
}
Accurate brand and style 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.
// 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
}
let itemMetadata = getItemMetadata() // From Step 2
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")")
}
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.