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
Before starting the capture flow, prepare the item details to pass to the SDK.
2.1 Authentication
For authentication captures, provide the brand and item_type for the item being authenticated. The SDK uses these values to match the item against the available capture flows configured for your account.
- Required fields
brand(String): The brand of the item (e.g., "Louis Vuitton", "Nike", "BAPE").item_type(String): The type of item (e.g., "Outerwear", "Tops", "Sneakers", "Bags").
- Optional fields
customer_item_id(String): Unique identifier from your system. Highly recommended for tracking.us_size(String): e.g., "8", "8.5", "8.5Y"style_code(String): e.g., "555088-134"upc(String): The item's Universal Product Code.
Capture Flow Selection Behavior
When you provide brand and item_type, the SDK evaluates them against the capture flows available to your account:
- Brand and item type both match a capture flow: the SDK takes the user directly to that capture flow.
- Only brand matches: the SDK presents the available item type options for that brand.
- Brand does not match (regardless of item type): the SDK presents the full capture flow menu for the user to select from.
Matching is case-insensitive and space/underscore-agnostic. For example, "Louis Vuitton", "louis_vuitton", and "LOUIS VUITTON" are all equivalent. The SDK matches against both internal identifiers and display names, so you can use either format.
Example
// Swift
func itemMetadata() -> [String: Any] {
return [
"brand": "BAPE",
"item_type": "Outerwear",
"customer_item_id": "ITEM-001"
]
}
Accurate item information is important for the authentication process. The available brands and item types depend on your account configuration. Consult Entrupy support if you need a list of supported values for your account.
2.2 Fingerprint
Fingerprint capture allows you to register an item's physical characteristics for future comparison or compare an item against previously registered fingerprints.
- Required fields
customer_item_id(String): Identifier from your systemitem_type(String): The type of itemcapture_workflow(String): Eitherfingerprint_registerorfingerprint_compare
2.2.1 Register
Use fingerprint_register to capture and register an item's fingerprint. If items with the same customer_item_id were previously registered, the SDK will display them for reference. You can then choose to:
- Continue registering the current item as a new fingerprint
- Cancel the operation
Example
// Swift
func fingerprintRegisterMetadata() -> [String: Any] {
return [
"customer_item_id": "ABC-abc-123445",
"item_type": "Bags",
"capture_workflow": "fingerprint_register"
]
}
2.2.2 Compare
Use fingerprint_compare to compare the current item against previously registered fingerprints. If multiple items with the same customer_item_id were registered, the SDK will display a list for you to select which one to compare against. You can then choose to:
- Select a specific registered item to compare against
- Cancel the operation
Example
// Swift
func fingerprintCompareMetadata() -> [String: Any] {
return [
"customer_item_id": "ABC-abc-123445",
"capture_workflow": "fingerprint_compare"
]
}
The same customer_item_id can be used to register multiple items. When comparing, you'll be prompted to select which registered instance to compare against.
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, including brand and item_type.
// 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 'brand' and 'item_type'
let itemMetadata = itemMetadata()
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.
3.1 Running a Pre-Result Hook
A pre-result hook lets your app run its own step after the user taps Submit and before the item is sent for review. The SDK does not know what the step is. It finishes uploading the images, calls your hook, and waits for your answer.
Call startCapture(forItem:viewController:preResultHook:). The SDK calls your hook on the main thread with the SDK view controller, so you can present your own screen on top of it. Answer with the EntrupyPreResultDecision:
decision.proceed(): the SDK submits the capture for review, and the flow continues as usual withdidCaptureCompleteSuccessfully.decision.cancel(): nothing is submitted. The user returns to an SDK hand-over screen, where Continue calls your hook again, or they can quit the capture with the close button.
// Swift
EntrupyApp.sharedInstance().startCapture(forItem: itemMetadata, viewController: self) { sdkViewController, decision in
// Show your own step on top of the SDK
showHostStep(
on: sdkViewController,
onDone: { decision.proceed() },
onClosed: { decision.cancel() }
)
}
// Objective-C
[[EntrupyApp sharedInstance] startCaptureForItem:itemMetadata
viewController:self
preResultHook:^(UIViewController *sdkViewController, EntrupyPreResultDecision *decision) {
// Show your own step on top of the SDK
[self showHostStepOn:sdkViewController
onDone:^{ [decision proceed]; }
onClosed:^{ [decision cancel]; }];
}];
Keep in mind:
- Answer once. Only the first answer counts, and you can answer from any thread. Releasing the decision without answering counts as
cancel(). - Dismiss your screen before you answer, for example in the completion of
dismiss(animated:completion:). If your screen is still animating out, the SDK waits for it to finish before it continues. If it is still open when you answer, the SDK dismisses it. - If your screen closes without a result, call
decision.cancel(). Otherwise the SDK keeps waiting. This includes a sheet the user swipes away: answer from that dismissal too, or setisModalInPresentation. - After
proceed(), the hook is not called again, even if the submission is retried. If the submission fails, the SDK shows an error alert. Retry submits again without calling the hook, and Cancel callsdidCaptureFailWithError, so your app can undo or retry its own step. - The 2-hour capture timeout keeps running while your step is open. If it expires, the SDK calls
didCaptureTimeout. - If the user quits from the hand-over screen, the SDK calls
didUserCancelCapture. - If the OS kills your app while a capture with a pre-result hook is open, the capture is lost and nothing is submitted.
- Only authentication captures call the hook. Fingerprint workflows and retakes submit without it.
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.