- Requirements and limitations
- Demo app
- Installation
- Create your own app
- Handle events
- Handle errors
- Customization
- Localization & internalization
WANNA UI SDK enhances your iOS app with 3D Viewer for handbags.
WANNA’s 3D Viewer for handbags was specifically crafted to answer the industry’s pain point — the high number of returns due to the wrong size of the bag. It provides users with a novel experience to understand the size and capacity of a bag and enables brands to showcase the product with the utmost realism. Such an experience is designed to help clients make an informed shopping decision by exploring the product's size, dimensions, texture, and key attributes before purchase.
Supported environments:
- iOS 14 and later
Working with WANNA UI SDK is subject to Terms of use. Please review them before downloading the SDK and starting to use it.
- A demo application showing the integration of our SDK using cocoapods.
Add WannaUI to your project as a cocoapods.
Create a Podfile if you haven't yet:
$ cd <your-project-directory>
$ pod init
Add pod WannaUI to your Podfile:
source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '15.0'
inhibit_all_warnings!
use_frameworks!
target 'MyApp' do
pod 'WannaUI'
end
Install the pod:
$ pod install
Open Example/Example.xcworkspace file in Xcode.
NOTE: when you open Example.xcodeproj instead of Example.xcworkspace it will result in compiler error No such module ‘WsneakersUISDK’
Create new or open existing Xcode project. Create new UIViewController.
- (optional) Check if the current environment supports WANNA SDK. It depends on the device or iOS version. You may want to hide the 3D button in unsupported environments.
guard WannaBags.Flow.isDeviceSupported else {
return "Device is unsupported"
}- Create the SDK config
let config = try WannaConfig.builder
.withCacheSize(megabytes: 200)
.withLicense("PUT_YOUR_LICENSE_HERE")
.build()In case you don't have a valid licence please contact [email protected]
- Setup flow
let flow = WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withErrorHandler { error in
// handle errors here
}
.withEventHandler { event in
// handle events here
}
.withProgressHandler { progress in
// Handle progress here
}- Start the flow and present preview view controller
let wannaViewController = try flow.start()
present(wannaViewController, animated: true)- (optional) To present content in view instead of fullscreen first implement extension:
extension UIViewController {
func addChild(_ childController: UIViewController, to view: UIView?) {
let view: UIView = view ?? self.view
childController.willMove(toParent: self)
addChild(childController)
view.addSubview(childController.view)
view.addBorderConstraints(to: childController.view)
childController.didMove(toParent: self)
}
} Then add wannaViewController to parent view:
let wannaViewController = try flow.start()
addChild(wannaViewController, to: previewContainer)- Full code sample
func viewDidLoad() {
super.viewDidLoad()
do {
// Setup WannaSDK
try setupWannaSDK()
} catch {
// Setup failed
}
}
func setupWannaSDK() throws {
// Create config
let config = try WannaConfig.builder
.withCacheSize(megabytes: 200)
.withLicense("PUT_YOUR_LICENSE_HERE")
.build()
// Setup flow
let flow = WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withProgressHandler { progress in
// Handle progress here
}
.withErrorHandler { error in
// Handle errors here
}
.withEventHandler { event in
// Handle events here
}
// Start the flow
let wannaViewController = try flow.start()
// Present it to container view
present(wannaViewController, animated: true)
}WANNA UI SDK allows you to track technical events:
- Implement event handler
func handleEvent(_ event: WannaBags.Event) {
switch event {
case .onModelLoaded(let modelId):
print("On model loaded: \(modelId)")
case .onDimensionsSwitched(let isActive):
print("On dimensions switched state: \(isActive)")
case .onPOISwitched(let index):
print("On Point of Interest switched to index: \(index)")
case .onRetry:
print("On retry button tapped")
}
}- Pass event handler to the flow
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withEventHandler { [weak self] event in
self?.handleEvent(event)
}| Event | Description |
|---|---|
.onModelLoaded(modelId: String) |
Model is loaded successfully. |
.onDimensionsSwitched(toActive: Bool) |
On dimensions button switched. |
.onPOISwitched(toIndex: String) |
On point of interest (POI) switched. |
.onRetry |
User tapped on retry button. |
WANNA UI SDK allows you to handle errors:
- Implement error handler
func handleError(_ error: WannaBags.Error) {
print("On Wanna SDK error: \(error)")
}- Pass error handler to the flow
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withErrorHandler { [weak self] error in
self?.errorHandler(error)
}| Error | Description |
|---|---|
.setModelFailed(modelId: String) |
Error during model update. |
.initializationFailed(error: Error) |
Initialization is failed. |
WANNA 3D Viewer provides default implementation but allows you to customize visual appearance.
Implement your custom progress view:
- Setup progress handler to update actual progress:
func handleProgress(_ progress: WannaProgress) {
switch progress {
case .loading(let progress):
// Show progress view, update progress
self?.progressView.isHidden = true
self?.progressView.progress = progress
case .finished:
// Hide progress view
self?.progressView.isHidden = false
}
}- Hide default loading view & pass custom progress handler to the flow
var uiSettings = WannaBags.UISettings()
uiSettings.loading.isHidden = true
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withUISettings(uiSettings)
.withProgressHandler { [weak self] progress in
self?.handleProgress(progress)
}Implement your custom errorView. Then integrate it to the SDK:
- Implement retry handler:
func onRetry() {
flow.retry()
errorView.isHidden = true
}- Hide default error view & pass custom error handler to the flow
var uiSettings = WannaBags.UISettings()
uiSettings.error.isHidden = true
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withUISettings(uiSettings)
.withErrorHandler { [weak self] error in
// Handle error
errorView.isHidden = false
}WANNA 3D Viewer allows you to localize all the text labels as well as set some specific content for displaying models.
A model can contain information about its dimensions in inches and centimetres. This info will be displayed in the 3D Viewer when the user taps on the corresponding UI button. Units used depends on user’s device locale. It is the same as Locale.current.usesMetricSystem. You can always update this setting.
var appearance: WannaAppearance = .default
appearance.usesMetricSystem = true/false
let config = try WannaConfig.builder
.withLicense("PUT_YOUR_LICENSE_HERE")
.withAppearance(appearance)
.build() You can localize the title for the widget that displays items which can be put inside a bag. The names of items aren’t localizable - this functionality will be supported in the next versions of the 3D Viewer.
var uiSettings = WannaBags.UISettings()
uiSettings.canHold.title = NSLocalizedString("Can hold", comment: "WannaSDK: Can hold widget")
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withUISettings(uiSettings)To enhance user’s experience, WANNA 3D Viewer can show onboarding screens to explain some available interactions with a model. SDK launches these onboarding screens when the user utilizes the 3D Viewer for the first time.
It's possible to disable onboarding.
var uiSettings = WannaBags.UISettings()
uiSettings.onboarding.isDisabled = true
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withUISettings(uiSettings)You can localize the labels for the onboarding widget
var uiSettings = WannaBags.UISettings()
uiSettings.onboarding.stepLocalizationHandler = { step in
switch step {
case .pinchToZoom:
return NSLocalizedString("Pinch to zoom", comment: "WannaSDK: onboarding")
}
}
WannaBags.Flow(config: config, modelId: "PUT_YOUR_MODEL_ID_HERE")
.withUISettings(uiSettings)| Step | Description |
|---|---|
.pinchToZoom |
"Pinch to zoom" onboarding step |