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 ConfigTyp

value

The parameter value as number , string or ImageDataParameter.

Return value

Returns a Promise which resolves to undefined.

setMaterialByColorOverlay

The asynchronous setMaterialByColorOverlay() method of the Configurator interface sets a material input to a base material and an image that is used as overlay color for this material

Signature

async setMaterialByColorOverlay(materialInputId: string, materialId: string, overlay: string | ImageDataParameter, size: [number, number]): Promise<void>

Parameters

materialInputId

Id of the material input as set up in the template editor.

materialId

Id of the base material to use. This e.g. determines the woven pattern.

overlay

The image to add as overlay color to the material, either specified as url or in-memory image specified as ImageDataParameter .

size

Physical size of the specified input image in cm.

Return value

Returns a Promise which resolves to void.

setMaterialByMaterialId

The asynchronous setMaterialByMaterialId() method of the Configurator interface assigns a material to a material input. The material is chosen by its colormass uuid.

Signature

async setMaterialByMaterialId(materialInputId: string, materialId: string): Promise<void>

Parameters

materialInputId

Id of the material input as set up in the template editor.

materialId

colormass' id of the material.

Return value

Returns a Promise which resolves to void.

setMaterialByArticleId

The asynchronous setMaterialByArticleId() method of the Configurator interface assigns a material to a material input. The material is chosen by the customer's article id.

Signature

async setMaterialByArticleId(materialInputId: string, articleId: string): Promise<void>

Parameters

materialInputId

Id of the material input as set up in the template editor.

articleId

Customer's id of the material.

Return value

Returns a Promise which resolves to void.

setNumber

The asynchronous setNumber() method of the Configurator interface assigns a number to a number input.

Signature

async setNumber(numberInputId: string, value: number): Promise<void>

Parameters

numberInputId

Id of the number input as set up in the template editor.

value

Value to be assigned to the number input.

Return value

Returns a Promise which resolves to void.

setImage

The asynchronous setImage() method of the Configurator interface assigns a number to a number input.

Signature

async setImage(imageInputId: string, value: string | number | ImageDataParameter): Promise<void>

Parameters

imageInputId

Id of the image input as set up in the template editor.

value

Value to be assigned to the image input. This is either a url, a numeric id of a data object or an in-memory image specified as ImageDataParameter .

Return value

Returns a Promise which resolves to void.

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 .

Syntax

addEventListener("changeCompleted", (event: { id: string}) => {}): 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
}