shopar-plugin

v1.2.0

Published

15 hours ago

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

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.
skuData (optional)
- Type: SkuData
- If provided, the API call is skipped and this data is used instead. This is useful for providing product data directly without relying on the ShopAR Dashboard API.
- See SkuData for the full type reference.
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. This includes both user interaction (mouse scroll, pinch touch) and programmatic zoom.
- 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
onMaxZoomEnter (optional)
- Type: () => void
- If provided, it will be called when the maximum zoom level (maxZoom) is reached in 3D.
onMaxZoomLeave (optional)
- Type: () => void
- If provided, it will be called when the zoom level moves away from the maximum (maxZoom) in 3D.
onMinZoomEnter (optional)
- Type: () => void
- If provided, it will be called when the minimum zoom level (minZoom) is reached in 3D.
onMinZoomLeave (optional)
- Type: () => void
- If provided, it will be called when the zoom level moves away from the minimum (minZoom) in 3D.
onMinVerticalAngleEnter (optional)
- Type: () => void
- If provided, it will be called when the minimum vertical angle is reached in 3D. This corresponds to the camera being positioned at the top of the orbit, looking down at the object.
onMinVerticalAngleLeave (optional)
- Type: () => void
- If provided, it will be called when the vertical angle moves away from the minimum in 3D. The camera is no longer at the top of the orbit.
onMaxVerticalAngleEnter (optional)
- Type: () => void
- If provided, it will be called when the maximum vertical angle is reached in 3D. This corresponds to the camera being positioned at the bottom of the orbit, looking up at the object.
onMaxVerticalAngleLeave (optional)
- Type: () => void
- If provided, it will be called when the vertical angle moves away from the maximum in 3D. The camera is no longer at the bottom of the orbit.
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
onFirstAREngagement (optional)
- Type: function
- If provided, it will be called the first time the user's subject is detected in AR (e.g. face, feet, wrist). Fires only once per setup.
onFirst3DEngagement (optional)
- Type: function
- If provided, it will be called the first time the user engages with the 3D view (rotate, pan or zoom). Fires only once per setup.
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.

SkuData

The skuData option allows you to provide product data directly, bypassing the ShopAR Dashboard API call. All properties are optional.

| Property | Type | Description | | --- | --- | --- | | category | AssetCategory | Product category. Supported values: 'Glasses', 'Shoes', 'Watches', 'Bracelets', 'Handbags', 'Rings', 'Bottles', 'Scarves', 'Hats', 'Necklaces', 'Earrings'. | | arUrl | string | URL to the AR model asset. | | arEnvUrl | string | URL to the AR environment map. | | arDiamondEnvUrl | string | URL to the AR diamond environment map. | | arToneMapping | ToneMapping | Tone mapping mode for AR. Supported values: 'ACES', 'Linear', 'Neutral'. | | arToneMappingExposure | number | Tone mapping exposure for AR. | | arBloomEnabled | boolean | Whether bloom is enabled in AR. | | arBloomStrength | number | Bloom strength in AR. | | arBloomRadius | number | Bloom radius in AR. | | arBloomThreshold | number | Bloom threshold in AR. | | arKey | string | License key for AR. | | arPromptEnabled | boolean | Whether the AR prompt overlay is shown. | | arPromptText | string | Custom text displayed in the AR prompt. | | arPromptImage | string | URL to a custom AR prompt image. If not provided, a default bundled image is used. | | previewUrl | string | URL to the 3D preview model asset. | | previewEnvUrl | string | URL to the 3D preview environment map. | | previewDiamondEnvUrl | string | URL to the 3D preview diamond environment map. | | previewToneMapping | ToneMapping | Tone mapping mode for 3D preview. Supported values: 'ACES', 'Linear', 'Neutral'. | | previewToneMappingExposure | number | Tone mapping exposure for 3D preview. | | previewBloomEnabled | boolean | Whether bloom is enabled in 3D preview. | | previewBloomStrength | number | Bloom strength in 3D preview. | | previewBloomRadius | number | Bloom radius in 3D preview. | | previewBloomThreshold | number | Bloom threshold in 3D preview. | | previewPosterUrl | string | URL to a poster image shown before 3D loads. | | cameraErrorText | string | Custom text shown when camera access fails. | | qrPromptText | string | Custom text shown on the QR code screen. |

License

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme