Skip to main content

Experience SDK

npm version bundle size

artlabs Experience is the SDK for artlabs platform to enhance web applications with Augmented Reality (AR) and Virtual Try-On (VTO) capabilities. This library integrates various modules to provide a seamless experience in product visualization and interaction.

Installation

Via NPM

Install the ES module using npm:

npm install artlabs-experience

Via Script Tag

You can directly UMD build to your HTML page:

<script src="https://assets.artlabs.ai/js/experience/latest/artlabs-experience.umd.js" />

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

Usage

To start using the library, you must import the ArtlabsExperience module in your JavaScript file:

import ArtlabsExperience from 'artlabs-experience';

Or, if you're using named exports:

import { init, startAR, startVTO } from 'artlabs-experience';

If you're using the UMD build, you can access the library via the global ArtlabsExperience object:

Then initialize the library with your token. It's a zero-config by default, but you can pass your configuration options as well. You can join the platform and get your API key at artlabs.ai.

ArtlabsExperience.init({
token: 'YOUR_API_KEY_HERE',
});

Config

To initialize the ArtlabsExperience library with custom settings for the Augmented Reality (AR) and Virtual Try-On (VTO) experiences, pass the configuration options as shown in the example below. Modify the options to suit your application's requirements:

Common Options

OptionDefault ValueDescription
localeenSets SDK language. Accepts ISO language codes. Accepts ISO language codes. Available locales are; en, de, fr, es, it, nl, no

AR Options

OptionDefault ValueDescription
debugModefalseEnables additional logging for debugging purposes.
showBannerfalseControls the visibility of a banner in the AR experience.
bannerType'default'The type of banner displayed in the AR experience.
bannerButtonText'Add to Cart'The text of the banner displayed in the AR experience.

VTO Options

OptionDefault ValueDescription
debugModefalseEnables additional logging for debugging purposes.
fontFamily'inherit'The font family used in the VTO experience interface.
disableUIfalseIf true, the default user interface for VTO will be disabled.
logoUrlfalseURL of the logo to be displayed in the VTO experience.
useWatermarkfalseDetermines whether a watermark is displayed in the VTO screenshot.
showBannerfalseControls the visibility of action buttons in the VTO experience.
bannerButtonText'Add to Cart'The text of the banner displayed in the VTO experience.

Example Config

ArtlabsExperience.init({
token: 'YOUR_API_KEY_HERE',
config: {
locale: 'en',
vto: {
fontFamily: 'inherit', // Customize the font for the UI
disableUI: false, // Set to true to disable the default UI
showBanner: true, // Set to true to display a banner in VTO
bannerButtonText: 'Add to Cart', // Customize the text for the VTO banner button
logoUrl: 'https://example.com/path/to/logo.png', // Provide a URL for your custom logo
useWatermark: true, // Set to true to include a watermark in screenshots
},
ar: {
debugMode: false, // Set to true to enable debugging
showBanner: true, // Set to true to display a banner in the AR experience
bannerType: 'default', // Specify a custom banner type,
bannerButtonText: 'Add to Cart', // Customize the text for the AR banner button
},
},
});

It's also possible to update the configuration after the initialization:

// It's also possible to override the configuration options after the initialization
ArtlabsExperience.setConfig({
locale: 'de',
vto: {
showBanner: true, // Set to true to display a banner in VTO
},
ar: {
showBanner: true, // Set to true to display a banner in the AR experience
},
});

Starting AR and VTO Experiences

Invoke AR or VTO experiences with product SKUs and configuration:

// Start AR Experience
await ArtlabsExperience.startAR('PRODUCT_SKU', {
// Optional product metadata to show in AR banner
product: {
title: 'Product Title',
subtitle: 'Product Subtitle',
price: '100$',
},
});

// Start VTO Experience.
// You can pass multiple SKUs as comma separated string or a single SKU
await ArtlabsExperience.startVTO('PRODUCT_SKU1,PRODUCT_SKU2,PRODUCT_SKU3');

// Stop VTO Experience
await ArtlabsExperience.stopVTO();

// Change product in experience
await ArtlabsExperience.changeProduct('PRODUCT_SKU4');

Events

There are multiple events that can be listened to. You can register an event listener via invoking the addEventListener method.

ArtlabsExperience.addEventListener('event-name', callbackFunction);
ArtlabsExperience.removeEventListener('event-name', callbackFunction);
Event Name       Description
ar-banner-clickTriggered when a user clicks on the AR banner. This event is dispatched with an object containing the sku of the product and the productConfig.
vto-loadEmitted when the VTO experience begins loading. It signifies that the resources and assets for the VTO are being fetched and initialized.
vto-change-productDispatched when there is a change in the product displayed during the VTO experience, allowing for dynamic updating of the product being tried on.
vto-banner-clickTriggered when a user clicks on the VTO banner. This event is dispatched with an object containing the sku of the product and the productConfig.
vto-screenshotSent out when the user clicks the shutter button and takes screenshot
vto-stopSent out when the VTO experience is terminated, either by user action or programmatically.
vto-errorFired when an error occurs within the VTO experience. It sends a message detailing the error, which can be used for debugging or user feedback.

Checking for AR and VTO Availability

Sometimes you may want to check if the current product has enabled AR or VTO experiences so you can show/hide relevant buttons. You can do that by invoking the checkAvailability method.

const availabilityResult = await ArtlabsExperience.checkAvailability('SKU1');

// availabilityResult will be an object with the following properties:
// {
// SKU1: {
// ar: true,
// vto: true,
// },
// }

Bundle Size

bundle size

You'll be consuming around 70kb minified and Gzipped or Brotli compressed versions, depending on the browser.

Desktop Behavior

As AR technology is only available on mobile devices, users on a desktop will need to be guided to their mobile devices. Both SDK's will do that for you on a desktop browser, using a runtime-generated QR code and a guidance popup.