@wannaby/wanna-ui

WANNA 3D Viewer for Handbags: Getting Started

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.

The WANNA 3D Viewer is delivered as a React component to be used together with the WANNA SDK for Web, which provides the core experiences. The 3D Viewer has an easy-to-customize UI that could be easily integrated into a webpage.

This document provides a detailed description of the 3D Viewer installation and usage.

• System Requirements
• License
• Installation and Usage
  • Simple Installation
  • Import and Launch
    • Example
  • Extended Installation
• Component Props
  • Models Prop
  • Header Component
  • Loading Component
  • FooterLeft and FooterRight Components
• Labels
• 3D Viewer Launch Example
  • Package.json
  • App.js

System Requirements

Supported environments:

• iOS - for both iPhones and iPads:
  • Safari 14 and later
  • Safari 14 (in-app) and later
  • Google Chrome on iOS 14.3 and later
• Android - for both mobile phones and tablets:
  • Google Chrome 88 and later
  • Android WebView
  • Android Browser 103 and later
  • Samsung Internet 17.0 and later
• Windows:
  • Google Chrome 103 and later
  • Mozilla Firefox 102 and later
  • Edge 103 and later
• Mac OS:
  • Google Chrome 102 and later
  • Safari 15.4 and later
  • Mozilla Firefox 102 and later
• Linux:
  • Google Chrome 102 and later

License

To work with WANNA SDK you need a license key. Contact our sales representative at [e-mail] to get one.

Installation and Usage

Simple Installation

To install the WANNA 3D Viewer, add both @wannaby/wanna-ui and @wannaby/wanna-sdk to your project dependencies:

yarn add @wannaby/wanna-ui @wannaby/wanna-sdk

Import and Launch

1. Import the WANNA UI component and it's styles from wanna-ui. Note: In this guide, the WannaUI name is used to refer to this component.
2. Import WANNA SDK to your project from wanna-sdk library.
3. Launch the 3D viewer by calling the component and passing the following parameters:
   • license - Your license key received from the WANNA team.
   • mode - This parameter is reserved for future use. In this version, only wannaSdk.MODE_TYPE_3D works.
   • modelsType - This parameter is reserved for future use. In this version, only wannaSdk.MODEL_TYPE_BAG works.
   • models - The models list. Only one model can be passed to the component. If you specify several models in an array, only the first one is shown in the 3D Viewer. You can find below the detailed description of available props.

Example

import wannaSDK from '@wannaby/wanna-sdk';
import WannaUI, { VIEW_MODE_MOBILE }  from '@wannaby/wanna-ui';
import '@wannaby/wanna-ui/styles.css';

<WannaUI
  wannaSdk={wannaSDK}
  models={[
    {
      id: 'model_id',
      brand: 'Brand Name',
      name: 'Model Name',
      price: '$ 1,200',
      pois: [
        '',
        'Text that will be displayed for the 2nd POI',
        'Text that will be displayed for the 3rd POI',
      ],
    },
  ]}
  license="your_license_key"
  mode={wannaSDK.MODE_TYPE_3D}
  modelsType={wannaSDK.MODEL_TYPE_BAG}
/>

Extended Installation

By default, wanna-ui uses an iframe hosted by WANNA, but you can override it by including an iframe in your build and host it yourself.

Add the following rules into your Webpack configuration:

rules: [
  ...
  {
    test: /@wannaby\/wanna-sdk\/.*iframe.html$/,
    loader: 'file-loader',
  },
  {
    test: /@wannaby\/wanna-sdk\/.*core.js$/,
    loader: 'file-loader',
    options: {
      name: 'core.js',
    },
   },
]

If instead of Webpack you use Rollup JS, or something similar, you must add some rules like that to add core.js and iframe.html files into your public folder and get the iframe.html path to import it, as shown in the example below.

Import iframe.html and core in your application and pass the iframeSrc prop to the Wanna UI component:

import wannaSDK from '@wannaby/wanna-sdk';
import WannaUI from '@wannaby/wanna-ui';
import wannaSdkIframe from '@wannaby/wanna-sdk/iframe.html';
import '@wannaby/wanna-sdk/core';
import '@wannaby/wanna-ui/styles.css';

<WannaUI
  wannaSdk={wannaSDK}
  iframeSrc={wannaSdkIframe}
  models={[
    {
      id: 'model_id',
      brand: 'Brand Name',
      name: 'Model Name',
      price: '$ 1,200',
      pois: [
        '',
        'Text that will be displayed for the 2nd POI',
        'Text that will be displayed for the 3nd POI',
      ],
    },
  ]}
  license="your_license_key"
  mode={wannaSDK.MODE_TYPE_3D}
  modelsType={wannaSDK.MODEL_TYPE_BAG}
/>

Component Props

The following props are supported in the WannaUI component:

Prop Name	Type	Description
wannaSdk	String	SDK instance from @wannaby/wanna-sdk (required)
license	String	License key to use the SDK and component (required)
models	Array	Model list as described in “Models Prop” below (required)
theme	wannaSDK.THEME_LIGHT | wannaSDK.THEME_DARK	UI theme (default: wannaSDK.THEME_LIGHT) Note! There is a known issue with Samsung browser on Android devices. When the dark mode is ON, the system changes the UI colors for the 3D Viewer. Thus to guarantee the appropriate UI view, WANNA recommends always using the dark theme for Samsung browser on Android devices
mainColor	String	Custom color for loading indicator and the model picker in RGB (example: #1E1E1E); default color depend on the UI theme
logoURL	String	URL referencing a custom logo image; if specified, is displayed on the loading screen
brandImageURL	String	URL referencing a brand logo image; if specified, is displayed as the brand name instead of the brand text
modelsType	wannaSDK.MODEL_TYPE_BAG	Currently supports only wannaSDK.MODEL_TYPE_BAG to work with handbags
mode	wannaSDK.MODE_TYPE_3D	Currently supports only wannaSDK.MODE_TYPE_3D to work with the 3D Viewer
headerComponent	React.Component	Custom header component; see “Header Component” below
footerLeftComponent	React.Component	Custom footer left component; see “FooterLeft and FooterRight Components” below
footerRightComponent	React.Component	Custom footer right component; see “FooterLeft and FooterRight Components” below
loadingComponent	React.Component	Custom loading component, see “Loading Component” below
font	Object	Custom font for the interface, expressed as { file: string, family: string}; by default, Roboto Google font is used
viewMode	VIEW_MODE_DESKTOP | VIEW_MODE_MOBILE	View mode for the component, exported from @wannaby/wanna-ui (default: VIEW_MODE_MOBILE)
dimensionsUnit	wannaSDK.MODE_3D_DIMENSIONS_CM | wannaSDK.MODE_3D_DIMENSIONS_INCH	Length dimension unit: (default: wannaSDK.MODE_3D_DIMENSIONS_CM)
showOnboarding	Boolean	Indicates whether onboarding should be shown to user or not (default: false)
labels	Object	Localization object; see “Labels” below
onError	(error) => void	Callback that is called when an error occurs
onModelSet	(modelId) => void	Callback that is called when the model has been set after successful loading
onModelLoadingFail	(modelId) => void	Callback that is called when the model loading fails.
onModelLoadingSuccess	(modelId) => void	Callback that is called when the model loading succeeds
onModelLoading	(modelId) => void	Callback that is called when model loading starts
onHeaderBackClick	() => void	Callback that is called when the user clicks the Back button in the header
onModel3dPoiChanged	({ poi, modelId }) => void	Callback that is called when the user clicks on POI and it has been changed
onModel3dShowReferences	({ modelId }) => void	Callback that is called when the user clicks on Dimensions and it has been displayed;

Models Prop

The model list (models prop) supports the following fields:

Field Name	Type	Description
id	String	Model ID (required)
image	String	URL to image that will be displayed in the loading screen
brand	String	Model brand name to be displayed in the header
name	String	Name that will be displayed in the header
price	String	Price that will be displayed in the header
pois	[String | Null, …]	Used in model POIs list in order of dots in the model

Note: For the pois field, a maximum of three values can be specified. Any additional values are ignored.

Header Component

WANNA provides full flexibility to customize the provided UI. You can use your own custom Header component by passing it as render-prop in the headerComponent prop. This component is used in the Wanna UI component and the Error screen.

headerComponent will receive the following props:

Prop Name	Type	Description
appWasInit	Boolean	Indicator that the app is ready; false in the Error and Rotate screens, true only in the Wanna UI component when the app was successfully initialized
brand	String	Model brand name
name	String	Model name
brandImageUrl	String	URL referencing the brand image
modelID	String	Model ID
style	Object	Style object
mode	wannaSDK.MODE_TYPE_3D	Mode of SDK initialization; currently can be only wannaSDK.MODE_TYPE_3D
viewMode	VIEW_MODE_DESKTOP | VIEW_MODE_MOBILE	View mode of the component, exported from @wannaby/wanna-ui

Loading Component

To match your website better, you can use your own custom Loading component by passing it as render-prop in the loadingComponent property. This component will be used in the Main component during the initialization and a model loading.

loadingComponent will receive the following props:

Prop Name	Type	Description
children	React.Node	Text label
progress	Number	Number from 0 to 100 inclusive, indicating the progress of the model’s loading
image	URL	Image to be shown with the loading indicator
loadingColor	String	Color of loading indicator in hex RGB (example: #1E1E1E)
theme	wannaSDK.THEME_LIGHT | wannaSDK.THEME_DARK	UI theme
modelsType	wannaSDK.MODEL_TYPE_BAG	Model type to work with; currently can be only wannaSDK.MODEL_TYPE_BAG
mode	wannaSDK.MODE_TYPE_3D	Mode of SDK initialization; currently can be only wannaSDK.MODE_TYPE_3D
type	LOADING_TYPE_INIT | LOADING_TYPE_MODEL | LOADING_TYPE_MODE_CHANGE	Loading type; useful if you need to distinguish the loading screen for the SDK initialization and model loading, exported from @wannaby/wanna-ui

FooterLeft and FooterRight Components

You can fully customize the footer by using your own custom footer components and passing them as render-prop in the footerRightComponent and footerLeftComponent properties. These components are used in the Main component footer when the component is initializing and a model is loading.

footerRightComponent and footerLeftComponent support the following props:

Prop Name	Type	Description
viewMode	VIEW_MODE_DESKTOP | VIEW_MODE_MOBILE	View mode of the component, exported from @wannaby/wanna-ui
screenInteraction	Boolean	Indicator that the user has touched the screen; valid for 3D mode
on3dZoomOut	() => void	Zoom out (“minus” button) handler (for desktop mode)
on3dZoomIn	() => void	Zoom in (“plus” button) handler (for desktop mode)
onToggleReferences	() => void	Size reference toggle handler
model	Object	Current selected model object from the models list
activeShowReference	Boolean	Indicates whether the reference mode is on (true) or off (false)
onboardingIsRunning	Boolean	Indicates whether onboarding is in progress

Labels

All texts visible in the 3D Viewer UI are available as labels. You can pass your own values for these labels to edit them or localize to your specific local languages. You can find the default label values in the table below.

Label	Default Value
canHold	Can hold
cantDownloadModel	Can't download the model.
cantToggleDimensions	Can't toggle model dimensions.
cantZoomInTheModel	Can't zoom in the model.
cantZoomOutTheModel	Can't zoom out the model.
cantResetTheModel	Can't reset the model.
cantChangeTheModelViewpoint	Can't change the model viewpoint.
doubleClickToFocus	Double click to select focus point.
doubleTapToFocus	Double tap to select focus point.
generating	Generating
modeChanging	Changing mode…
noImage	No image
loadingModel	Loading model…
pinchToZoom	Pinch to zoom.
pleaseComeBackLater	Please come back later.
rotateThePhoneFor3d	Rotate the phone to view in 3D.
somethingWentWrong	Something went wrong, but we’re working on it.
starting3dViewer	Starting 3D Viewer…
useWiFi	Use a Wi-Fi network to start faster.

3D Viewer Launch Example

Package.json

"wannaby/wanna-sdk": <version>,
"wannaby/wanna-ui": <version>

App.js

import wannaSDK from '@wannaby/wanna-sdk';
import WannaUI, { VIEW_MODE_DESKTOP } from '@wannaby/wanna-ui';
import '@wannaby/wanna-ui/styles.css';

const models = [
  {
    id: 'model_id',
    brand: 'Brand Name',
    name: 'Model Name',
    price: '$ 1,200',
    pois: [
      '',
      'Text that will be displayed for the 2nd POI',
      'Text that will be displayed for the 3rd POI',
    ],
  },
];

const license = 'license_string';

function App() {
  return (
    <div>
      <PreviewModels
        wannaSdk={wannaSDK}
        models={models}
        license={license}
        mode={wannaSDK.MODE_TYPE_3D}
        viewMode={VIEW_MODE_DESKTOP}
        modelsType={wannaSDK.MODEL_TYPE_BAG}
        theme={wannaSDK.THEME_LIGHT}
      />
    </div>
  );
}

export default App;