Integration into Your App

Since you know best how to approach your customers, the product presentation and selection is done by your app and not the ip.labs Mobile SDK. But we provide you with some convenience APIs to map the ip.labs product portfolio to the product information of your app in order to create a seamless experience for your users.

Retrieving the Product Portfolio

You can retrieve all products in your portfolio with a simple call to retrieveProductPortfolio, which returns either a portfolio or a corresponding error:

let result = await IplabsMobileSdk.shared.retrieveProductPortfolio()

switch result {
case .success(let portfolio):
    print(portfolio.products)
case .failure(let error):
    print(error)
}

The retrieveProductPortfolio method comes as an async variant or with a completionHandler if you haven’t adopted async / await in your Swift codebase yet.

Since you can modify the portfolio content in our backend systems, this call will always fetch the latest version of the portfolio and therefore requires an internet connection. You can however persist returned data if you have a need for it.

The portfolio contains a list of type Product.

Products & Options

Every customizable photo product in the ip.labs infrastructure is identified by a numeric ID, which you should map to an equivalent of a product in your shop system. This product ID is also necessary to launch our editor with this product.

A product can also have a set of options, which are used to describe different variants of it. Wall décor products for example can have an option for the material (like canvas, aluminum, or Forex^®). Typically these options are presented to the user in the product selection UI, e.g. in a dropdown component.

The data types provided by the ip.labs Mobile SDK also include some additional information, like name or description, which contain translated strings depending on the locale:

public struct Product: Decodable {
    public let id: Int
    public let name: String
    public let options: [ProductOption]
    public let bestPrice: Double
    public let description: String?
}

Option Values

Each product option is identified through an id string and can have a certain set of option values:

public struct ProductOption: Codable {
    public let id: String
    public let name: String
    public let values: [ProductOptionValue]
    public let defaultValue: String
    public let description: String?
}

name and description contain translated strings depending on the locale. The defaultValue maps to the id of one of the values. When building a UI for product selection, you should use this to initialize the components for this option (e.g. a dropdown) with the corresponding value as a default.

The type ProductOptionValue has a structure similar to the option itself:

public struct ProductOptionValue: Codable {
    public let id: String
    public let name: String
    public let description: String?
}

Initializing the Editor With an Empty Product

To let your users design a product and personalize it to their needs with photos and other decorative elements, you need to initialize an EditorView first. The essential parameter, that you have to provide to properly set it up during initialization, is a ProductConfiguration. With that, you control, which product in which variant will be loaded. Take a look at the examples:

let editorViewController = IplabsMobileSdk.shared.initializeEditor(
    // Use proper values for id and options instead, based on your portfolio and
    // the user’s choices
    productConfiguration: ProductConfiguration(
        id: 50046830,
        options: [
            "color": "red",
            "handedness": "right"
        ]
    )
)

editorViewController.modalPresentationStyle = .fullScreen

self.present(editorViewController, animated: true)

Editor Configuration

Optionally, you can also pass an EditorConfiguration to the initialization call, in case you want to adjust the behavior of some of the editor’s features. For details on that please refer to the corresponding documentation of available customizations.

Checking for Unsaved Changes in the Editor

Before leaving the editor e.g. because a navigation to a different screen in your app was triggered, we recommend to check whether the user has unsaved changes in the current project first. You can do so with the requestTermination method of EditorViewController. This will display a dialog asking the user to either save or discard pending changes in case there are any (or even cancel the process if they change their mind):

To handle such a termination request you can pass a callback to requestTermination (or use the async overload), which will give you an EditorTerminationState as well as a result to indicate whether the user has unsaved changes after confirming the dialog.

@IBAction func backButtonTapped(_ sender: UIButton) {
    editorViewController.requestTermination() { editorState in
       if editorState == .savedWork {
            // navigate back and clean up
        }
    }
}