shopar-plugin

v1.1.0

Published

14 days ago

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

Downloads

51,496

0High
0Medium
0Low

deepar

ShopAR AR VTO Virtual try-on 3D preview 360° product viewer DeepAR

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.

ShopAR Plugin

Getting started

Create an account in the ShopAR Dashboard.

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.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/shopar-plugin.js"></script>

It is possible to use a different CDN instead of jsDelivr (e.g. cdnjs, unpkg), 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 for more details).

via NPM

Add shopar-plugin to your project:

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

Usage

Paste the following snippet in your 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.
Replace PRODUCT_ID with the ID of the product. Make sure it matches the plugin SKU of the model in the ShopAR Dashboard.
Replace TARGET_ELEMENT with the HTML element you wish to embed the plugin's UI into.

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

Styling

To change the look-and-feel of the plugin's UI, use CSS custom properties (variables). Set them on the target element or any ancestor:

#my-target-element {
  /* Hide 3D loading bar */
  --shopar-3d-loading-display: none;

  /* Move 3D loading bar to bottom */
  --shopar-3d-loading-top: auto;
  --shopar-3d-loading-bottom: 0;

  /* Change 3D loading bar appearance */
  --shopar-3d-loading-radius: 0;
  --shopar-3d-loading-fg: #f28232;
  --shopar-3d-loading-bg: transparent;

  /* Change 3D background */
  --shopar-3d-bg: linear-gradient(to top, #1a88ff, #003e80);

  /* Hide AR loading screen */
  --shopar-ar-loading-container-display: none;

  /* Change AR loading bar appearance */
  --shopar-ar-loading-bar-radius: 0;
  --shopar-ar-loading-bar-fg: #000000;
  --shopar-ar-loading-bar-bg: #f0f0f0;

  /* Change AR prompt appearance */
  --shopar-ar-prompt-bg: #161616b2;
  --shopar-ar-prompt-text-color: #f0f0f0;

  /* Change QR code screen appearance */
  --shopar-qr-bg: #f0f0f0;

  /* ...see full reference below... */
}

| Variable | Default | Description | | --- | --- | --- | | --shopar-3d-bg | #ffffff | 3D view background color. | | --shopar-3d-loading-display | block | 3D loading bar display. Set to none to hide. | | --shopar-3d-loading-top | 0 | 3D loading bar top position. | | --shopar-3d-loading-bottom | auto | 3D loading bar bottom position. | | --shopar-3d-loading-height | 0.375rem | 3D loading bar height. | | --shopar-3d-loading-radius | calc(infinity * 1px) | 3D loading bar border radius. | | --shopar-3d-loading-fg | linear-gradient(90deg, #773cd8, #5fb9ec) | 3D loading bar foreground (progress). | | --shopar-3d-loading-bg | #e5e7eb | 3D loading bar background. | | --shopar-ar-loading-container-display | flex | Loading container display. Set to none to hide. | | --shopar-ar-loading-container-bg | #ffffff | Loading container background color. | | --shopar-ar-loading-container-gap | 1rem | Gap between loading elements. | | --shopar-ar-loading-bar-width | 80% | Loading bar width. | | --shopar-ar-loading-bar-height | 0.5rem | Loading bar height. | | --shopar-ar-loading-bar-radius | calc(infinity * 1px) | Loading bar border radius. | | --shopar-ar-loading-bar-fg | linear-gradient(90deg, #773cd8, #5fb9ec) | Loading bar foreground (progress). | | --shopar-ar-loading-bar-bg | #e5e7eb | Loading bar background. | | --shopar-ar-prompt-bg | #1e293bb2 | AR prompt background color. | | --shopar-ar-prompt-gap | 1rem | Gap between AR prompt elements. | | --shopar-ar-prompt-text-color | white | AR prompt text color. | | --shopar-ar-prompt-img-max-width | 80% | AR prompt image max width. | | --shopar-ar-prompt-img-max-height | 50% | AR prompt image max height. | | --shopar-qr-bg | #ffffff | QR code container background. |

Default UI

By default, the plugin renders its own UI which includes control buttons (to switch between 3D and AR) and error UI. This is useful for quick start and prototyping.

Tip: For production use, we recommend implementing a custom UI instead. This allows you to track user interactions with your own analytics and integrate the plugin seamlessly into your existing design system.

You can customize its appearance using CSS variables:

| Variable | Default | Description | | --- | --- | --- | | --shopar-btn-container-padding-bottom | 2rem | Button container bottom padding. | | --shopar-btn-container-gap | 0.5rem | Gap between buttons. | | --shopar-btn-padding | 0.5rem 0.75rem | Button padding. | | --shopar-btn-gap | 0.25rem | Gap between button icon and text. | | --shopar-btn-border | 1px solid #dddddd | Button border. | | --shopar-btn-border-radius | calc(infinity * 1px) | Button border radius. | | --shopar-btn-bg | #ffffff | Button background color. | | --shopar-btn-hover-bg | #f5f5f5 | Button hover background color. |

Custom UI

For production, we recommend building your own UI. This lets you add analytics tracking and integrate seamlessly with your existing design.

Set defaultUI: false and use the provided API methods:

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;

API

ShopAR.plugin.setup(options)

This method fetches the specified product from the ShopAR Dashboard 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/[email protected]/dist
defaultUI (optional)
- Type: boolean
- If provided and set to false, disables the default UI (buttons and error UI).
- 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...
  - prompt.ar.{category}: undefined
debounceAREngagementMs (optional)
- Type: number
- If provided, it will be used as the debounce duration for debounced AR engagement tracking.
- Default value: 2000
onDebouncedAREngagement (optional)
- Type: function
- If provided, it will get called with the engagement duration on every (debounced) AR engagement.
- AR engagement is measured as the time spent by the user virtually trying out the product in AR.
debounce3DEngagementMs (optional)
- Type: number
- If provided, it will be used as the debounce duration for debounced 3D engagement tracking.
- Default value: 2000
onDebounced3DEngagement (optional)
- Type: function
- If provided, it will be called with the engagement duration on every (debounced) 3D engagement.
- 3D engagement is measured as the time spent by the user rotating, panning or zooming the product in 3D.

License

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme