3D Viewer

You have two options for web integrations. The first option provides both a 3D view and an AR button, while the second option goes directly into AR inside the phone camera.

For the time being, AR is only available on mobile devices because it requires a back camera to operate. In both options; when users try to open AR on the desktop, a popup window guides the user to their phone with a QR code.

1: Viewer & AR SDK

Install

The <artlabs-viewer> web component can be used directly from either unpkg.com, npm or artlabs cdn

You'll need to paste script code before closing </body> tag of your web page

<script
  type="module"
  src="https://unpkg.com/artlabs-viewer/dist/artlabs-viewer.min.js"
  data-artlabs-key="YOUR_API_KEY"
></script>

caution

Make sure to replace YOUR_API_KEY with your API key.

Usage

After initialized, on a specific product page, call SDK with product identifier. (SKU)

<artlabs-viewer sku="YOUR_SKU" />

SDK will do the rest.

Options

Name	Default	Description
`sku`	required	SKU of your product. Identifier for 3D assets.
`width`	`100%`	CSS width of parent component. Accepts px, em, rem, vw.
`height`	`300px`	CSS height of parent component. Accepts px, vh, vw.
`auto-rotate`	`false`	Should model rotate automatically.
`disable-interaction-prompt`	`false`	Disables the interaction prompt that appears when the model is loaded.
`show-zoom-buttons`	`false`	Shows zoom controls.
`reveal`	`auto`	Determines when to load and reveal 3D model. Values; `auto` As soon as model loaded. `interaction` Reveals model after first user interaction `manual` the model will remain hidden until `dismissPoster()` is called.
`config`	`null`	Configuration object for additional settings.
`extra`	`null`	Extra product information such as price, description to be displayed in AR banner. Required if `show-banner` enabled.
`show-banner`	`false`	Should show a banner with Add to Cart button in iOS AR.
`banner-type`	`default`	Type of iOS AR banner. Possible values are `default`, `custom` and `apple-pay`. Apple Pay includes a checkout with Apple Pay button.
`show-dimensions`	`false`	Should show the dimensions of model in centimeters.
`custom-dimensions`	`null`	Custom dimensions for the model, if different from default.
`show-wireframe`	`false`	Displays the model in wireframe mode.
`viewer-style`	`null`	Object to customize the viewer's style.
`disable-ar`	`false`	Disables AR mode, hides View in AR button.
`disable-poster`	`false`	Disables the poster image that appears before the model is loaded.
`disable-zoom`	`false`	Disables zoom functionality.
`show-annotations`	`false`	Enable model annotations.
`hide-annotation-text`	`false`	When enabled, annotation markers are still shown and focusing still moves the camera, but the text popup is suppressed (marker-only mode). Requires `show-annotations`.

Methods

Name	Description
`dismissPoster`	Meant to use with `reveal='manual'`. Dismisses the poster image and loads 3D model
`focusAnnotation`	Programmatically focus an annotation: pass an index (`number`) of an existing annotation, or a custom coordinates object. Returns `true` if applied. Requires `show-annotations`.
`closeAnnotation`	Closes the annotation popup and restores the default camera.

Example;

const artlabsViewer = document.getElementById('artlabs-viewer');
artlabsViewer.dismissPoster();

Focusing annotations from outside the SDK

Call focusAnnotation() to focus an annotation in response to your own UI (e.g. a button on your product page). Call it after the product-fetched event, since annotations are created once the product loads.

const artlabsViewer = document.querySelector('artlabs-viewer');

artlabsViewer.addEventListener('product-fetched', () => {
  // Focus an existing annotation by its index (0-based):
  artlabsViewer.focusAnnotation(0);

  // Or focus an arbitrary point with custom coordinates. This drops a
  // temporary marker at position/normal and moves the camera. Only
  // `position` (or `orbit`) is required; everything else is optional.
  artlabsViewer.focusAnnotation({
    position: '0 0.1 0',
    normal: '1 0 0',
    orbit: '0.8rad 0.83rad 0.33m',
    target: '0 0.1 0',
    fov: '30deg',
    header: 'Custom point',
    text: 'Focused programmatically.',
  });

  // Close the popup and restore the default camera:
  artlabsViewer.closeAnnotation();
});

Events

Some events can be listened to. You can register an event listener using addEventListener method.

Product Fetched

Fired once the product data has loaded and the model is set up. The event detail contains the product. This is the recommended point to call methods that depend on a loaded model, such as focusAnnotation().

const artlabsViewer = document.querySelector('artlabs-viewer');
artlabsViewer.addEventListener('product-fetched', (e) => {
  console.log(e.detail); // product data
});

Added to Cart

When user clicks the Add to Cart button in AR banner, this event will be fired with SKU.

const artlabsViewer = document.querySelector('artlabs-viewer');
artlabsViewer.addEventListener('add-to-cart', (e) => {
  // Add product to cart
  console.log(e.detail.sku);
});

Full Example

<head>
  <script
    type="module"
    src="https://unpkg.com/artlabs-viewer/dist/artlabs-viewer.min.js"
    data-artlabs-key="YOUR_API_KEY"
  ></script>
</head>

<body>
  <artlabs-viewer
    sku="Nike-Air-Max-90"
    height="500px"
    show-banner
    banner-type="default"
    extra='{"price": "$500", "description":"White, Essential"}'
  ></artlabs-viewer>
</body>

<script>
  const artlabsElement = document.querySelector('artlabs-viewer');
  artlabsElement.addEventListener('add-to-cart', (e) => {
    console.log('Product added to cart :: ', e.detail.sku);
  });
</script>

UX Recommendations

When integrating 3D visualization into your product pages, you have two primary implementation strategies:

First Page Load Integration: Include the 3D viewer directly in your initial page load for an immediate immersive experience. This works well for products where 3D visualization is a key selling point.
Manual 2D/3D Switch: Implement a toggle between traditional 2D images and 3D visualization, giving users control over their viewing experience. This approach is ideal when you want to maintain a familiar interface while offering enhanced 3D capabilities.

Here's an example of a clean product page example with a "Show in 3D" button:

Example of 3D viewer integration in a product page

Bundle Size

artlabs-viewer loads progressively. Initial load is very small, around 20kb. As the browser requires, it will load additional assets.

1: Viewer & AR SDK​

Install​

Usage​

Options​

Methods​

Focusing annotations from outside the SDK​

Events​

Product Fetched​

Added to Cart​

Full Example​

UX Recommendations​

Bundle Size​