shopar-plugin
Version:
Plugin for the Web that seamlessly integrates into your webpage to create embedded virtual try-on and 3D preview capabilities.
200 lines (166 loc) • 6.16 kB
Markdown
# 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