@wannaby/wanna-sdk 2.2.6 → 2.2.9

package/README.md

@@ -1,52 +1,560 @@
-# How to use
+# Get started with WANNA SDK
 
-## Install library
+WANNA SDK enhances your website with virtual try-on experience for sneakers and watches, which works directly in a mobile web browser without installing any apps.
 
-1) Add the library localy in package.json
-```js
-    "wanna-sdk": "file:~Downloads/wanna-sdk"
+<!-- TOC -->
+- [Requirements and limitations](#requirements-and-limitations)
+- [License](#license)
+- [Installation](#installation)
+- [Usage](#usage)
+- [Example](#example)
+<!-- /TOC -->
+
+## Requirements and limitations
+
+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 account@wanna.fashion to get one.
+
+## Installation
+
+1) Add `@wannaby/wanna-sdk` package to your project dependencies
+```
+    yarn add @wannaby/wanna-sdk
 ```
-OR
 
-1) Add the library remotely in package.json
+2) Add the following rules into your Webpack configuration:
 ```js
-    "wanna-sdk": "https:// ... .tar.gz"
+rules: [
+  ...
+  {
+    test: /@wannaby\/wanna-sdk\/.*iframe.html$/,
+    loader: 'file-loader',
+  },
+  {
+    test: /@wannaby\/wanna-sdk\/.*core.js$/,
+    loader: 'file-loader',
+    options: {
+        name: 'core.js',
+    },
+  },
+]
 ```
 
-## Import files
-TODO: add webpack config to use the library without importing /core manualy (3rd line)
+If instead of Webpack you use Rollup JS, or something similar, you have to add some rules like that to add core.js and iframe.html files into your public folder and get iframe.html path to import it in the example below.
+
 
-2) Import wanna sdk files
+*Note:* Some platform providers will restrict the use of the hosted frame. Check the headers for the following settings:
+
+* `frame-ancestors` in the CSP header set to `deny`, or to a host or scheme different from the page that runs WANNA SDK (see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors)
+* `X-Frame-options` set to `DENY` (see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)
+
+These settings may prevent your using the hosted frame on other pages. In that case host our files elsewhere and specify the full paths to these files in **index.html** and the `iframeSrc` parameter of the `init` method.
+
+## Usage
+
+1) Import Wanna SDK files
 ```js
-import wannaSdk from 'wanna-sdk'
-import wannaSdkIframe from 'wanna-sdk/iframe'
-import 'wanna-sdk/core'
+import wannaSdk from '@wannaby/wanna-sdk'
+import wannaSdkIframe from '@wannaby/wanna-sdk/iframe.html'
+import '@wannaby/wanna-sdk/core'
 ```
 
-3) Init wanna sdk ussing imported iframe
+2) *(optional)* Check if the current environment supports WANNA SDK. It depends on the device and browser. You may want to hide the virtual try-on button in unsupported environments.<br>
 ```js
-wannaSdk.init({
+await wanna.checkEnvironment()
+```
+
+3) Initialize the WANNA library using the `init` method. Pass in the element where the virtual try-on will be rendered, license string that authorizes your use of WANNA SDK, type of session (`wannaSdk.MODEL_TYPE_SNEAKER` or `wannaSdk.MODEL_TYPE_WATCH`), the link to the iframe, and optionally the iframe size (by default it takes up the whole container):
+```javascript
+await wanna.init({
+    container: '<HTML_container_id>',
     iframeSrc: wannaSdkIframe,
-    ...
+    type: wannaSdk.MODEL_TYPE_SNEAKER,
+    license: '<PUT_YOUR_LICENSE_STRING_HERE>',
 })
-``` 
+```
+The good time to initialize is when the user goes to the page that offers virtual try-on and you expect them to use it. Note that initialization will take up some processing resources and download traffic on the user's device. To prevent overuse of these resources, avoid initializing too early. On pages that are showing the whole range of content your website offers, wait until the user actually chooses virtual try-on.
 
-4) Add webpack config for iframe.html.
+4) *(optional)* Call the `initVideo` method to check and request camera permissions, and start showing the video stream once they are granted. Call it at the same time as the `init` method or immediately afterwards.
+
+The purpose of this step is to show the user some activity while the library is initializing. Once the video is initialized, you may display the `root` element that will have the raw camera output:
 ```js
-{
-    test: /wanna-sdk\/.*iframe.html$/,
-    loader: 'file-loader',
-},
+wanna.initVideo().then(() => {
+    showElement('<HTML_container_id>')
+})
 ```
-`NOTE: Check all webpack config that iframe.html is processing just by this config, not html-loader and etc!`
 
-5) Add webpack config for core.js
+5) *(optional)* Download from the CDN the model that will be used for virtual try-on. This will reduce the time to start up the try-on experience, as the model will be loaded and ready when you go to the next step.<br>
 ```js
-{
-    test: /wanna-sdk\/.*core.js$/,
-    loader: 'file-loader',
-    options: {
-        name: 'core.js',
+await wanna.downloadModel({ id: 'wanna01' })
+```
+
+If you know the model ID — for example, because of starting up on the particular product's page—we recommend downloading the model immediately after the initialization completes, to save the user's time. If step 2, `init`, has completed before step 3, `initVideo`, just start downloading the model without waiting for the video.
+
+6) Start the try-on session. If you haven't done it beforehand, the method will first download the model, then render it on the screen.<br>
+```js
+await wanna.downloadAndSetModel({ id: 'wanna01' })
+```
+
+**Important:**
+
+- If the user hasn't granted access to the camera, virtual try-on will not work. Handle the `NotAllowedError` to tell the user that camera access is required.
+- For non-localhost addresses, HTTPS is required for correct operation of the camera.
+- The SDK initialization can fail on unsupported devices. In this case, the `init` method will return an error. Handle errors using `try...catch` statement. Please use the code samples provided together with the SDK as a reference implementation.
+
+## Example
+
+```js
+import wannaSdk from '@wannaby/wanna-sdk'
+import wannaSdkIframe from '@wannaby/wanna-sdk/iframe.html'
+import '@wannaby/wanna-sdk/core'
+
+async function runExample () {
+  const canInit = await wannaSdk.checkEnvironment()
+
+  if (canInit) {
+    try {
+      await Promise.all([
+        wannaSdk.initVideo(),
+        wannaSdk.init({
+          container: '<HTML_container_id>',
+          iframeSrc: wannaSdkIframe,
+          type: 'sneakers',
+          license: '<PUT_YOUR_LICENSE_STRING_HERE>',
+        }),
+      ])
+    } catch {
+      console.error('Try-on not available')
+      return
+    }
+    
+    try {
+      await wanna.downloadAndSetModel({ id: 'wanna01' })
+    } catch (error) {
+      if (error.name === 'NotAllowedError') {
+        // Ask user to allow camera access or check site settings
+      }
+    }
+  } else {
+    console.error('Environment does not fit requirements')
+  }
+}
+
+runExample()
+```
+
+# WANNA SDK Web API Reference
+
+This document describes JavaScript API of WANNA SDK. It enhances your website with augmented reality (AR) try-on experience for sneakers and watches, which works directly in a mobile web browser without installing any apps.
+
+<!-- TOC -->
+- [Methods](#methods)
+  - [checkEnvironment](#checkenvironment)
+  - [init](#init)
+  - [initVideo](#initvideo)
+  - [downloadModel](#downloadmodel)
+  - [downloadAndSetModel](#downloadandsetmodel)
+  - [getCamerasList](#getcameraslist)
+  - [changeCamera](#changecamera)
+  - [startPipeline](#startpipeline)
+  - [pausePipeline](#pausepipeline)
+  - [getPipelineStatus](#getpipelinestatus)
+  - [takePhoto](#takephoto)
+  - [destroy](#destroy)
+- [Events](#events)
+  - [General](#general)
+  - [Resource loading](#resource-loading)
+  - [Camera](#camera)
+  - [Try-on object presence](#try-on-object-presence)
+<!-- /TOC -->
+
+## Methods
+
+The basic usage scenario requires you to `init`, then `downloadAndSetModel` to show the try-on and `destroy` the library when done.
+
+### checkEnvironment
+
+Checks if the SDK can work in the current environment: device and browser.
+
+```javascript
+checkEnvironment() => Promise<bool>
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that resolves with a boolean value indicating if the current environment is supported.
+
+### init
+
+Initializes the library, loading the resources required for try-on, except the 3D models. May be called several times with the same options.
+
+```javascript
+init(options) => Promise
+
+options: {
+    container:node|string,
+    license:string,
+    verbose?:bool=false,
+    type:string,
+    iframeSrc:string,
+    iframeSize?:{
+        width?:string|number='100%',
+        height?:string|number='100%',
+    modelsCacheSize?:number,
     },
-},
+}
+```
+
+#### Parameters
+
+Initialization options:
+
+* *container* — the DOM element in which the try-on session will be displayed, or its identifier
+* *license* — the string with WANNA SDK license information
+* *verbose* — (optional) specifies if the full log should be written; default value is `false`
+* *type* — the kind of product to try on: `'sneakers'` or `'watch'`;
+  **Note:** the previously used `'sneaker'` type is deprecated
+* *iframeSrc* — the path to **iframe.html**, found in the distribution pack; if it's at the same location as the page with the *container*, you don't have to specify this parameter
+  **Note:** the **core.js** script should be located at the same path as **iframe.html**
+* *iframeSize* `{width?: string|number='100%', height?: string|number='100%'}` — (optional) the width and height of the frame where the try-on will be rendered; by default it's the size of the container
+* *modelsCacheSize* — (optional) the limit to the number of 3D models that may be stored in cache; the default is 5
+
+#### Returns
+
+A promise that is resolved when the library is initialized successfully.
+
+### initVideo
+
+Asks the user for the camera permission and starts showing the stream from camera. Call this method either after `init` or at the same time with it, because the promise this method returns will only be resolved if `init` has been called.
+
+This method is designed to let you start showing the video as soon as possible. If you don't use it, the video stream will be shown when you call [`downloadAndSetModel`](#downloadandsetmodel) or [`startPipeline`](#startpipeline).
+
+```javascript
+initVideo() => Promise
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that is resolved when the required permissions are granted and the camera stream starts showing, but NOT if the `init` method wasn't called yet.
+
+### downloadModel
+
+Downloads the model from the CDN.
+
+```javascript
+downloadModel({id: string}) => Promise
+```
+
+#### Parameters
+
+* *id* — the unique identifier of the model, different for different colors
+
+#### Returns
+
+A promise that is resolved when the model is downloaded.
+
+### downloadAndSetModel
+
+Downloads the model from the CDN and renders it on the try-on screen as soon as it's ready. If you have already loaded the model with the help of `downloadModel`, this method will work faster.
+
+If you haven't started the pipeline yet, it will be started within this method call.
+
+```javascript
+downloadAndSetModel({id: string}) => Promise
+```
+
+#### Parameters
+
+* *id* — the unique identifier of the model, different for different colors
+
+#### Returns
+
+A promise that is resolved when the model is downloaded.
+
+### getCamerasList
+
+Lists all available device cameras that can be used to get the input video stream.
+
+**Note:** the method only works on Android.
+
+```javascript
+getCamerasList() => Promise
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that resolves with a list of string camera identifiers and human-readable labels: `[{id: 'cameraId1, label: 'cameraLabel1'}, {id: 'cameraId2', label: 'cameraLabel2'}, ...]`.
+
+### changeCamera
+
+Selects the camera to be used for the input video stream. Only call this method while the pipeline is active.
+
+**Note:** Android-only method.
+
+```javascript
+changeCamera(cameraId: string) => Promise
+```
+
+#### Parameters
+
+* *cameraId* — the camera identifier, taken from `getCamerasList`
+
+#### Returns
+
+A promise that is resolved when the view switches to the selected camera.
+
+### startPipeline
+
+Starts the virtual try-on. You may also start try-on directly with the [`downloadAndSetModel`](#downloadandsetmodel) method.
+
+```javascript
+startPipeline() => Promise
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that is resolved when the try-on session starts.
+
+### pausePipeline
+
+Pauses the virtual try-on. The raw camera view is still shown.
+
+```javascript
+pausePipeline() => Promise
 ```
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that is resolved when the try-on session pauses and the model is no longer rendered.
+
+### getPipelineStatus
+
+Checks if the pipeline is active.
+
+```javascript
+string getPipelineStatus()
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A string description of the current status. Can be one of:
+
+* `sdk.STATUS_PREPARING` — the library is loading
+* `sdk.STATUS_SDK_LOADED` — the library successfully loaded
+* `sdk.STATUS_INITIALIZING` — the pipeline is initializing
+* `sdk.STATUS_INITIALIZED` — the pipeline successfully initialized
+* `sdk.STATUS_RUNNING` — the pipeline is active
+* `sdk.STATUS_PAUSED` — the pipeline is paused
+* `sdk.STATUS_ERROR` — an error has occurred
+* `sdk.STATUS_WRONG_WORKING_CONDITIONS` — unsupported working conditions (for example, landscape orientation isn't supported)
+
+### takePhoto
+
+Makes a snapshot of the current try-on view.
+
+```javascript
+takePhoto() => Promise
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that resolves with a data blob containing the image.
+
+### destroy
+
+Unloads the library and detaches the iframe.
+
+All pending promises from WANNA SDK will be rejected with an error (error name will be `sdk.ERROR_SDK_DESTROYED`), but first the [`sdk.EVENT_DESTROYED`](#sdkevent_destroyed) event will be emitted, and you can handle the rejections gracefully using that.
+
+```javascript
+destroy() => Promise
+```
+
+#### Parameters
+
+No input parameters.
+
+#### Returns
+
+A promise that is resolved when the library is unloaded. Now you can initialize the SDK in another container.
+
+## Events
+
+The SDK informs you of various events occurring during initialization, model loading, etc. Listen to these events and handle the outcomes to show progress and hints to your users, manage the errors that may happen.
+
+### General
+
+#### sdk.EVENT_SDK_LOADED
+
+Occurs when the iframe and the scripts for it are loaded successfully.
+
+#### sdk.EVENT_INIT_STARTED
+
+Occurs when initialization starts.
+
+#### sdk.EVENT_INIT_FINISHED
+
+Occurs when initialization has finished successfully.
+
+#### sdk.EVENT_INIT_FAILED
+
+Occurs when initialization has failed.
+
+Arguments:
+
+* *error* — an `Error` object that describes the reason for the failure
+
+#### sdk.EVENT_ERROR
+
+Occurs when the SDK encounters an error.
+
+Arguments:
+
+* *error* — an `Error` object
+
+#### sdk.EVENT_DESTROYED
+
+Occurs at the [`destroy`](#destroy) method call. This event handler will be called before rejecting the WANNA SDK pending promises. Use it to handle the promises rejection gracefully.
+
+### Resource loading
+
+#### sdk.EVENT_RESOURCE_LOAD_STARTED
+
+Occurs when the SDK starts to download a resource.
+
+Arguments:
+
+* *type* — the kind of resource, for example, a 3D model or a neural network model
+* *id* — the identifier of the resource; for 3D models, it's the same ID that you use to `downloadModel` or `downloadAndSetModel`
+
+#### sdk.EVENT_RESOURCE_LOAD_PROGRESS
+
+Occurs while the resource is loading.
+
+Arguments:
+
+* *type* — the kind of resource, for example, a 3D model or a neural network model
+* *id* — the identifier of the resource; for 3D models, it's the same ID that you use to `downloadModel` or `downloadAndSetModel`
+* *progress* — percentage completed
+
+#### sdk.EVENT_RESOURCE_LOAD_FAILED
+
+Occurs when a resource couldn't be loaded.
+
+Arguments:
+
+* *type* — the kind of resource, for example, a 3D model or a neural network model
+* *id* — the identifier of the resource; for 3D models, it's the same ID that you use to `downloadModel` or `downloadAndSetModel`
+
+#### sdk.EVENT_RESOURCE_LOAD_FINISHED
+
+Occurs when the resource is loaded successfully.
+
+Arguments:
+
+* *type* — the kind of resource, for example, a 3D model or a neural network model
+* *id* — the identifier of the resource; for 3D models, it's the same ID that you use to `downloadModel` or `downloadAndSetModel`
+
+### Camera
+
+#### sdk.EVENT_CAMERA_CHANGED
+
+Occurs when the try-on is switched to use the view from a different camera.
+
+Arguments:
+
+* *cameraId* — the identifier of the camera now used
+
+#### sdk.EVENT_CAMERA_ACCESS_REQUESTED
+
+Occurs when the library needs camera access.
+
+
+#### sdk.EVENT_CAMERA_ACCESS_GRANTED
+
+Occurs when the user grants camera access.
+
+Arguments contain the data from [MediaStreamTrack](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack) object representing the raw stream from camera:
+
+* *id* — the identifier of the track
+* *kind* — the type of content, in this case `"video"`
+* *label* — the camera label
+* *muted* — indicates if the track is unable to provide the media data because of a technical issue
+* *readyState* — the status of the track: `"live"` or `"ended"`
+* *contentHint* — the string hint about the track content
+
+#### sdk.EVENT_CAMERA_ACCESS_FAILED
+
+Occurs when the camera can't be accessed, whether because the permission was refused or for another reason.
+
+Arguments:
+
+* *error* — an `Error` object that describes the reason for the failure
+
+### Try-on object presence
+
+#### sdk.EVENT_OBJECT_APPEARED
+
+Occurs when the object on which the try-on should be rendered appears in camera view.
+
+<!--Arguments:
+
+* *type* — the type of object: feet for sneakers, other objects for other products in future versions-->
+
+#### sdk.EVENT_OBJECT_DISAPPEARED
+
+Occurs when the object on which the try-on should be rendered disappears from camera view.
+
+<!--Arguments:
+
+* *type* — the type of object: feet for sneakers, other objects for other products in future versions-->
+