SDK API Reference

The configurator web component is a custom HTML element. Just as regular elements, it provides HTML attributes and methods, which are described in the following.

Attributes

Name	Type	Description	Default
parameters	string	Initial list of parameters formatted as query parameters, e.g, param(<input-identifier>)=<input-type>(<input-value>). Example: "param(123)=material(123)&param(987)=number(10)"	undefined
show-ui	boolean	Show or hide the action menu UI layer.	true
template-uuid	string	The id of the scene template.	undefined
use-external-menu	boolean	Set to true if a separate menu is being provided.	false

Methods

captureSnapshotInMemory

The asynchronous captureSnapshotInMemory() method of the Configurator interface creates an image from the rendering and resolves the returned Promise with the data URL string that contains the image data.

Throws an error if the Canvas 2d context is not available.

Signature

async captureSnapshotInMemory(): Promise<string>

Parameters

None

Return value

Returns a Promise which resolves with the data URL string

generateQrCode

The asynchronous generateQrCode() method of the Configurator interface creates an QR code image for the provided url and resolves the returned Promise with the data URL string that contains the image data.

The QR code image can be configured by setting the errorCorrectionLevel to 'high' or 'low' and by setting the width or margin number parameter.

Signature

async generateQrCode(url: string, errorCorrectionLevel: "high" | "low", width: number, margin: number): Promise<string>

Parameters

url

The url string the QR code should represent.

errorCorrectionLevel

The correction level that should be applied to the QR code generation. Can be 'high' or 'low'.

width

The number of the resulting image width in pixels.

margin

The number of the margin around the QR code in pixels.

Return value

Returns a Promise which resolves with the data URL string

getParameterList

The getParameterList() method of the Configurator interface returns a list of the available ConfiguratorParameters once the configurator is loaded (after the configurationLoaded event was fired).

Signature

getParameterList(): ConfiguratorParameters[]

Parameters

None

Return value

Returns an Array of Object conforming to the ConfiguratorParameters type.

getPricesAsList

The asynchronous getPricesAsList() method of the Configurator interface fetches a list of item price data, if configured on the platform. The Promise resolves with an array of PricedItem.

Signature

async getPricesAsList(): Promise<PricedItem[]>

Parameters

None

Return value

Returns a Promise which resolves with an Array of Object conforming to the PricedItem type.

loadConfigurator

The asynchronous loadConfigurator() method of the Configurator interface loads the template for the supplied template UUID and starts rendering.

Signature

async loadConfigurator(templatedUuid: string): Promise<void>

Parameters

templateUuid

The id string of the template to load.

Return value

Returns a Promise which resolves to undefined.

resetCamera

The resetCamera() method of the Configurator interface resets the camera angle and zoom level of the visualisation.

Signature

resetCamera(): void

Parameters

None

Return value

Returns undefined.

saveSnapshot

The saveSnapshot() method of the Configurator interface creates an image from the rendering and starts a file download.

Signature

saveSnapshot(): void

Parameters

None

Return value

Returns undefined.

setParameter

The asynchronous setParameter() method of the Configurator interface sets a parameter for the current template and starts rendering.

There is advanced guide on how to set parameters.

Signature

async setParameter(id: string, type: ConfigType, value: number | string | ImageDataParameter): Promise<void>

Parameters

id

The parameter identifier string.

type

The parameter ConfigType.

value

The parameter value as number , string or ImageDataParameter.

Return value

Returns a Promise which resolves to undefined.

toggleDimensionGuides

The toggleDimensionGuides() method of the Configurator interface shows or hides dimension guides, if guides are configured for the template.

Signature

toggleDimensionGuides(): void

Parameters

None

Return value

Returns undefined.

toggleFullscreen

The toggleFullscreen() method of the Configurator interface requests fullscreen view for the configurator and exits fullscreen respectively.

Signature

toggleFullscreen(): void

Parameters

None

Return value

Returns undefined.

viewInAr

The asynchronous viewInAr() method of the Configurator interface fetches the AR model for the current configuration and opens the native AR view on iOS or Android. For other devices it will generate and display a QR code, which links to the AR view.

Signature

async viewInAr(): Promise<void>

Parameters

None

Return value

Returns a Promise which resolves to undefined.

zoomIn

The zoomIn() method of the Configurator interface increases the zoom. It accepts a value between 0 and 1, where larger values produce larger zoom steps.

Signature

zoomIn(value: number): void

Parameters

value

The zoom percentage as a number between 0 and 1.

Return value

Returns undefined.

zoomOut

The zoomOut() method of the Configurator interface decreases the zoom. It accepts a value between 0 and 1, where larger values produce larger zoom steps.

Signature

zoomOut(value: number): void

Parameters

value

The zoom percentage as a number between 0 and 1.

Return value

Returns undefined.

Events

arUrl

The arUrl event fires when the AR model for the current configuration is ready. The URL string to open the AR viewer can be accessed via event.detail.

Syntax

addEventListener("arUrl", (event: { detail: string }) => {}): void

changeCompleted

The changeCompleted event fires after a parameter was changed using setParameter and the visualization change is done. The event.detail object contains the changed parameter id, type and value.

Syntax

addEventListener("changeCompleted", (event: { id: string, type: ConfigType, value: number | string | ImageDataParameter }) => {}): void

configurationLoaded

The configurationLoaded event fires after the configurator finished loading the configuration. It will fire for the initial configuration and on subsequent changes triggered through the menu UI, changes to attributes, calls to loadConfigurator or setParameter.

Syntax

addEventListener("configurationLoaded", (event) => {}): void

loadingCompleted

The loadingCompleted event fires after the configurator finished loading the template. It will fire for the initial configuration and if the template is changed via the template-uuid attribute or a call to loadConfigurator.

Syntax

addEventListener("loadingCompleted", (event) => {}): void

Types

ConfigType

type ConfigType = "config" | "material" | "material-article-id" | "template" | "image" | "string" | "boolean" | "number" | "object" | "int" | "float" 

ConfiguratorParameters

type ConfiguratorParameters = {
    id: string
    type: ConfigType 
    name: string
    values: {
      id: string
      name: string
    }[]
    value?: unknown
}

PricedItem

type PricedItem = {
    description: string
    sku?: string
    price: number
    currency: "EUR" | "USD" | "GBP"
    amount: number
}

ImageDataParameter

type ImageDataParameter = {
    contentType: "image/jpeg" | "image/png"
    data: Uint8Array
}