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 (UUID) of the template to load. Mutually exclusive with the organization-uuid/article-id pair (if both are supplied, template-uuid takes precedence).
undefined
organization-uuid
string
The id (UUID) of the organization used together with article-id to resolve a template by its article identifier. Required when article-id is provided and template-uuid is omitted.
undefined
article-id
string
The optional article identifier used (together with organization-uuid) to load a template without knowing its template UUID. If both template-uuid and article-id are present, the component uses template-uuid.
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.
loadConfiguratorByArticleId
The asynchronous loadConfiguratorByArticleId() method of the Configurator interface resolves a template via an organization UUID / article ID pair and then loads it. Use this when you only know a business-level article identifier within an organization instead of a specific template UUID.
Signature
loadConfiguratorByArticleId(organizationUuid: string, articleId: string): voidParameters
organizationUuid
The organization id string the article identifier belongs to.
articleId
The article identifier string unique within the organization.
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(): voidParameters
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(): voidParameters
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 | ColorOverlayParameter): 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.
toggleDimensionGuides
The toggleDimensionGuides() method of the Configurator interface shows or hides dimension guides, if guides are configured for the template.
Signature
toggleDimensionGuides(): voidParameters
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(): voidParameters
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): voidParameters
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): voidParameters
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
}ColorOverlayParameter
type ColorOverlayParameter = {
materialId: string
size: [number, number]
overlay:
| string
| {
data: Uint8Array<ArrayBuffer>
contentType: string
}
}Last updated