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
parameters
string
Initial list of parameters formatted as query parameters, e.g, param(<input-identifier>)=<input-type>(<input-value>). Example:
"param(123)=material(123)¶m(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 }) => {}): voidchangeCompleted
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}) => {}): voidconfigurationLoaded
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) => {}): voidloadingCompleted
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) => {}): voidTypes
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
}Last updated