Experience SDK
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
Option | Default Value | Description |
---|---|---|
locale | en | Sets SDK language. Accepts ISO language codes. Accepts ISO language codes. Available locales are; en, de, fr, es, it, nl, no |
AR Options
Option | Default Value | Description |
---|---|---|
debugMode | false | Enables additional logging for debugging purposes. |
showBanner | false | Controls 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
Option | Default Value | Description |
---|---|---|
debugMode | false | Enables additional logging for debugging purposes. |
fontFamily | 'inherit' | The font family used in the VTO experience interface. |
disableUI | false | If true , the default user interface for VTO will be disabled. |
logoUrl | false | URL of the logo to be displayed in the VTO experience. |
useWatermark | false | Determines whether a watermark is displayed in the VTO screenshot. |
showBanner | false | Controls 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-click | Triggered 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-load | Emitted when the VTO experience begins loading. It signifies that the resources and assets for the VTO are being fetched and initialized. |
vto-change-product | Dispatched 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-click | Triggered 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-screenshot | Sent out when the user clicks the shutter button and takes screenshot |
vto-stop | Sent out when the VTO experience is terminated, either by user action or programmatically. |
vto-error | Fired 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
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.