# ShopAR Plugin

Plugin for the Web that seamlessly integrates into your webpage to create embedded virtual try-on and 3D preview capabilities.

Powered and developed by DeepAR.

## Table of contents

- [ShopAR Plugin](#shopar-plugin)
  - [Table of contents](#table-of-contents)
  - [Getting started](#getting-started)
  - [Installation](#installation)
    - [via Script tag](#via-script-tag)
    - [via NPM](#via-npm)
  - [Usage](#usage)
  - [API](#api)
    - [ShopAR.plugin.setup(options)](#shoparpluginsetupoptions)
  - [License](#license)

## Getting started

Create an account in the [ShopAR Dashboard](https://dashboard.shopar.ai).

Add some models to your account. Make sure the models' plugin SKUs match the product IDs on your website.

## Installation

There are two distinct ways of integrating the plugin: via Script tag and via NPM.

### via Script tag

Add the following script to your HTML.

```html
<script src="https://cdn.jsdelivr.net/npm/shopar-plugin@0.8.9/dist/shopar-plugin.js"></script>
```

It is possible to use a different CDN instead of [jsDelivr](https://www.jsdelivr.com/) (e.g. [cdnjs](https://cdnjs.com/), [unpkg](https://www.unpkg.com/)), or even a relative path if the plugin is distributed as a static asset to your app. Just make sure to set the `baseUrl` parameter accordingly (see [setup options](#shoparpluginsetupoptions) for more details).

### via NPM

Add `shopar-plugin` to your project:

```shell
npm install shopar-plugin
# or
yarn add shopar-plugin
```

## Usage

Paste the following snippet in your HTML.

```html
<script>
  ShopAR.plugin.setup({
    apiKey: 'API_KEY',
    sku: 'PRODUCT_ID',
    targetElement: 'TARGET_ELEMENT',
  });
</script>
```

- Replace `API_KEY` with your API key. You can find it in the [ShopAR Dashboard](https://dashboard.shopar.ai).
- Replace `PRODUCT_ID` with the ID of the product. Make sure it matches the plugin SKU of the model in the [ShopAR Dashboard](https://dashboard.shopar.ai).
- Replace `TARGET_ELEMENT` with the HTML element you wish to embed the plugin's UI into.

To change the look-and-feel of the plugin's UI, modify the following CSS classes:

```css
.shopar-btn-container {
  /* Container for the control buttons. */
}
.shopar-btn {
  /* Control button. */
}
.shopar-btn:hover {
  /* Hovered control button. */
}
.shopar-loading-container {
  /* Container for the loading screen. */
}
.shopar-loading-text {
  /* Loading text. */
}
.shopar-loading-bar-bg {
  /* Loading bar's background. */
}
.shopar-loading-bar-fg {
  /* Loading bar's foreground. */
}
.shopar-loading-bar-fg.active {
  /* Loading bar's foreground when active. */
}
.shopar-qr {
  /* Container for the QR code. */
}
.shopar-ar-prompt {
  /* Container for the AR prompt. */
}
.shopar-ar-prompt-text {
  /* AR prompt text. */
}
.shopar-ar-prompt-img {
  /* AR prompt image. */
}
```

Alternatively, use your own UI:

```js
const shopAR = await ShopAR.plugin.setup({
  // ...
  defaultUI: false,
});

myARButton.onclick = shopAR.launchAR;
myARButton.disabled = shopAR.launchAR === undefined;
my3DButton.onclick = shopAR.launch3D;
myARButton.disabled = shopAR.launch3D === undefined;

myCloseARButton.onclick = shopAR.closeAR;
myCloseARButton.disabled = shopAR.closeAR === undefined;
myClose3DButton.onclick = shopAR.close3D;
myClose3DButton.disabled = shopAR.close3D === undefined;
// or just:
myCloseButton.onclick = shopAR.close;
myCloseButton.disabled = shopAR.close === undefined;
```

If you wish to change the SKU or target element at runtime, simply call `setup()` with different parameters.

## API

### ShopAR.plugin.setup(options)

This method fetches the specified product from the [ShopAR Dashboard](https://dashboard.shopar.ai) and renders the plugin's UI.

Options used for the plugin setup:
- `apiKey`
  - Type: `string`
  - API key found in the ShopAR dashboard.
- `sku`
  - Type: `string`
  - Product identifier.
- `targetElement`
  - Type: `HTMLElement`
  - The element to inflate with ShopAR UI.
  - Its CSS position property must be either `static` or `relative`.
- `initialState` (optional)
  - Type: `'AR' | '3D'`
  - If provided, defines which preview type the plugin initializes to.
- `baseUrl` (optional)
  - Type: `string`
  - If provided, defines where the additional ShopAR plugin files are fetched from.
  - Default value: `https://cdn.jsdelivr.net/npm/shopar-plugin@0.8.9/dist`
- `defaultUI` (optional)
  - Type: `boolean`
  - If provided and set to `false`, disables the default UI such as buttons, loading and error views.
  - Default value: `true`
- `interactive` (optional)
  - Type: `boolean`
  - If provided and set to `false`, disables user interactivity by ignoring input events.
  - Default value: `true`
- `touchAction` (optional)
  - Type: `string`
  - If provided, the corresponding touch scroll behavior will be used in 3D.
    - `'none'`: Touch gestures are never interpreted as scrolling. This might be useful if 3D occupies the whole viewport.
    - `'pan-x'`: Touch gestures that start horizontally are interpreted as scrolling.
    - `'pan-y'`: Touch gestures that start vertically are interpreted as scrolling.
  - Default value: `'pan-y'`
- `zoomEnabled` (optional)
  - Type: `boolean`
  - If provided and set to `false`, disables zoom in 3D by ignoring mouse scroll or pinch touch events.
  - Default value: `true`
- `minZoom` (optional)
  - Type: `number`
  - If provided, it will be used as the minimum zoom level in 3D.
  - Default value: `0.625`
- `maxZoom` (optional)
  - Type: `number`
  - If provided, it will be used as the maximum zoom level in 3D.
  - Default value: `5`
- `alwaysTransparentBackground` (optional)
  - Type: `boolean`
  - If provided and set to `true`, transparent background will always be used in 3D.
- `initialAnimation` (optional)
  - Type: `string` or `KeyFrameConfig[]`
  - If provided, replaces the default interactivity animation in 3D with a custom one.
- `strings` (optional)
  - Type: `object`
  - If provided, overrides strings in the UI.
  - Default values:
    - `loading.ar`: `Loading Try On...`
    - `loading.3d`: `Loading 3D...`

## License

Please see: https://developer.deepar.ai/customer-agreement