9.3.0 - 3D Product Configurator Integrations Guide

Implementing On a Website

The 3D Product Configurator front end code can be implemented on customer facing websites through several methods. Defined below are options an implementing developer can use to integrate with a website.

Front End Application Supported Browsers and Devices

Chrome	51+
Firefox	54+
Edge	14+
Safari	10+ (except 15.0; 15.1+ supported)
Opera	38+
Internet Explorer	Not supported
Edge iOS	Not supported

Front End Application URL Parameters

● ?config=<configId>

○ The Id of the configurator to load, used for debugging purposes a developer should pass in the configurator id in the initialization functions of the API for production use.

● ?storeId=<storeId>

○ Store Id used for Analytics

● ?sku=<sku>

○ Sku of the current chair loaded, auto updated on swapping steps

● ?preview=<true/false>

○ This parameter is for testing purposes only and will force the application to always load the latest version of the configurator.

Adding the library from the 3D Cloud CDN

Ask your account team for your specific CDN URLs.

JS example:
1. https://cdn.3dcloud.io/{client_specific_folder}/x.x.x/MxtProductConfigurator-x.x.x.js
Minified JS example (should be used in production environments)
1. https://cdn.3dcloud.io/{client_specific_folder}/x.x.x/MxtProductConfigurator-x.x.x.min.js
CSS example:
1. https://cdn.3dcloud.io/{client_specific_folder}/x.x.x/MxtProductConfigurator-x.x.x.css
Initiating the application example:

<!DOCTYPE html>
<html>
<head>
    <title>MxtModularConfigurator Example</title>
    <link href="https://cdn.3dcloud.io/mxt-kongfigurator/9.3.0/MxtProductConfigurator-9.3.0.css" rel="stylesheet">
    <style>
        .mxt-full-modal-screen {
            width: 80%;
            height: 100%;
            position: absolute;
        }
    </style>
</head>
<body>
    <div id="spins-test-container" class="mxt-full-modal-screen"></div>
    <script src="https://cdn.3dcloud.io/mxt-kongfigurator/9.3.0/MxtProductConfigurator-9.3.0.min.js"></script>
    <script>
        async function initializeUnitConfig() {
            const unitConfig = new MxtProductConfigurator.MxtKongfigurator({
                spinCommon: {
                    apiKey: '{user api key provided by 3D Cloud}',
                    element: document.getElementById('spins-test-container'),
                    expandButton: {},
                    webArMode: "OnDemand"
                },
                spin3d:{
                    camera: {},
                    screenshot: {},
                },
                assetEnvironment: '{Active OR Stage}',
                configurationId:  '{configurator ID to load}',
            });
            await unitConfig.init();
        }
        initializeUnitConfig();  // Call the function
    </script>   
</body>
</html>

Initialization

When initializing, there are two things that MUST be true about the HTML element that you pass in (or the parent element for the viewer container, see the Components section below)

It MUST have a defined height and width, whether that is an absolute value (like 600px) or a percentage of its parent that has an absolute value (for example 50% of the page width/height). This is because the 3d canvas has no defined size in and of itself, so we have no “size to build out”, so to speak. Additionally, if a size is NOT given, the 3d render engine will spin out of control attempting to render in a 0x0 space.
(for 3d render type only) It MUST be not be display:none while the engine is running. By default, the engine starts running on init. IF you want to init the MxtKongfigurator in a hidden container, use the option spin3d.loadPaused. The 3d renderer will spin out of control when attempting to render to a non-visible container. By using the option spin3d.loadPaused, the renderer will start in a paused mode. In order to start the rendering engine when the container is made visible, call the run() method. To re-pause the renderer, call the stop() method.

Minimum Required Options

When constructing the class for the product configurator there are required options and optional options that you will set for the product configurator to function properly. These are the three required options that you must always set.

Option Name	Option Description
spinCommon.apiKey	API Key provided by 3D Cloud™(required)
configurationId	the unique id of the configurator to load (required)
spinCommon.element	The element that the Configurator will be built within. Some sort of specific height and width must be given, otherwise the app will not have any size. This is due to the fact that the rendering canvas has no inherent size. (required)

Basic Optional Options

These options are optional and are the most commonly set by developers implementing the product configurator on their website.

SpinCommon options

These options are applicable to the render view for both 2d and 3d renders, and live under spinCommon, i.e.

const configurator = new MxtProductConfigurator.MxtKongfigurator({
    spinCommon: {
        apiKey: '{user api key provided by 3D Cloud}',
        ...
    },
});

apiKey and element are covered above.

Option Name	Option Description
`loadingIconColor`	CSS string defining color of loading progress bar.
`loadingIconBackgroundColor`	CSS string defining color of loading progress bar background.
`services?: { environment?: MSServiceEnvironment; };`	The environment of services to hit. Defaults to production.
logging	Sets the log level which can be pulled from log.levels namespace; `TRACE: 0; DEBUG: 1; INFO: 2; WARN: 3; ERROR: 4; SILENT: 5;` Defaults to WARN

AR Options

Part spinCommon options.

webArMode?: WebArMode;
webArOptions?: MxtSpinsWebArOptions;

WebArMode defaults to WebArMode.None.

WebArMode.Pregenerated will attempt to get an AR asset that has already been generated and stored based on the current sku(s). If none exists, then no web AR asset will be available.
WebArMode.OnDemand will look up an existing AR asset based on sku(s), but if one does not exist, a new one will be generated when a user requests one.

webArOptions.enableScaling - by default, scaling on USDZ is turned off. If you wish to enable, set this flag

Customizing Text and Icons Options

This only applies to spinCommon options:

To customize icons used in the renderer view:

icons: {
    about?: string;
    close?: string;
    collapse?: string;
    presetView?: string;
    presetViewActive?: string;
    download?: string;
    downloadInverse?: string;
    downloadActive?: string;
    expand?: string;
    rotateLeft?: string;
    rotateRight?: string;
    spinner?: string;
    webAr?: string;
    webArInverse?: string;
    zoomIn?: string;
    zoomOut?: string;
}

To customize text:

customText in the format {[language: string]: any;} where language is a language ISO code (https://www.metamodpro.com/browser-language-codes), for example:

customText : {
    en: {
      about: {
          appName: "My example app name"
      }
    }    
};

Rather than providing an exhaustive list of every available key, please contact us with the text you desire to override, and we will provide you with the appropriate key(s).

spin3d Options

These options are applicable to the render view for 3d renders only, and live under spin3d, i.e.

const configurator = new MxtProductConfigurator.MxtKongfigurator({
    spin3d: {
        camera: {}
        ...
    },
});

Option Name	Option Description
`loadPaused`	Use this if you dont want the 3d render loop to start immediately upon initialization. Use especially if you are initializing in a hidden div or one with no size. Call run() method to start the 3d render loop whenever the div becomes visible.
`zoomDelta`	`Zoom Delta - in meters; defaults to .3`
`rotateDelta`	`Rotate Delta - in radians; defaults to .3`
`fitToScreenMultiplier`	The amount of screen that a product should “fill” when initially loaded; essentially default zoom level but relative to product size
`maxDistanceMultiplier`	Effectively max zoom, relative to the default zoom level
`showGuidance`	`If not provided, defaults to on if panning is turned on, and defaults to off if panning is turned off. If true, then will create guidance with panning guidance if panning is allowed, and guidance without panning if panning is not allowed`

Camera Options

Part spin3d options. All nested within a “camera” options object, i.e.

spin3d: {
    camera: {
      allowPanning: true,
      ...
    }
},

Option Name	Option Description
`allowPanning`	If true, right click pans the camera rather than rotates the camera. Panning is limited to bounds of product.
`defaultAlpha`, `defaultBeta`
`lowerBetaLimit`	`Minimum camera angle that the camera can rotate vertically`
`upperBetaLimit`	`Maximum camera angle that the camera can rotate vertically`
`lowerAlphaLimit`	Minimum camera angle that the camera can rotate horizontally
`upperAlphaLimit`	Maximum camera angle that the camera can rotate horizontally

Hotspot Options

Part spin3d options. All nested within a “hotspots” options object, i.e.

spin3d: {
    hotspots: {
      invisibleOnLoad: true,
      ...
    }
},

Option Name	Option Description
`invisibleOnLoad`	There is a hotspot toggle in the UI. By default, hotspots show up when there are hotspots and the UI toggle is on. This defaults the UI toggle to off so that the user has to manually toggle the hotspots on.
`hotspotMeshBasePath`	URL base path for a hotspot mesh; we provide a default hotspot mesh, but a custom one can be provided by using this + `hotspotMeshFilename`
`hotspotMeshFilename`	Filename of hotspot mesh. Must be a GLB/GLTF file. URL is created by doing `hotspotMeshBasePath` + `hotspotMeshFilename`.

Customizing 3D viewer Icon Options

This only applies to spin3d options:

To customize icons used in the 3drenderer view:

icons: {
    hotspotToggle?: string;
    hotspotToggleActive?: string;
    hotspotToggleInverse?: string;
    dimensions?: string;
    dimensionsActive?: string;
    dimensionsInverse?: string;
    panningGuidanceMouse?: string;
    panningGuidanceMousePan?: string;
    panningGuidanceDrag?: string;
    panningGuidanceTwoFingerDrag?: string;
}

Dimension Options

Part spin3d options. All nested within a “dimensions” options object, i.e.

spin3d: {
    dimensions: {
      enabled: true
      ...
    }
},

Option Name	Option Description
`enabled`	Enable/disable dimensions. Enabled by default
`color`	Color of dimension lines: `{ r: 0.5921, g: 0.5921, b: 0.5921, a: 1 }` by default (light blue)
`unitType`	Unit type to display for dimensions; defaults to inches.
`visibleOnLoad`	If dimensions should be visible on load. Defaults to off, users must toggle it on
`lineScale`	Size of line
`arrowScale`	Size of arrows at the end of the line

Preset Views Options

Part spin3d options. All nested within a “presetViews” options object, i.e.

spin3d: {
    presetViews: {
      enabled: true
      ...
    }
},

Option Name

Option Description

enabled

Enable/disable preset views. Enabled by default

views

We supply default preset views. To override these, provide an array of objects in format:

{   
    id: string;
    displayName: string;
    icon: string;
    azimuth: number;
    elevation: number;
}

Screenshot Options

Part spin3d options. All nested within a “screenshot” options object, i.e.

spin3d: {
    screenshot: {
      width: 1024
      ...
    }
},

Option Name	Option Description
`enabled`	By default, enabled.
`width`	`By default, screenshot 1024x1024. May specify a different width, or set to -1 to use size on screen`. If using a value other than -1, note that cropping may occur if your aspect ratio on screen does not match the aspect ratio defined here
`height`	`By default, screenshot 1024x1024. May specify a different height, or set to -1 to use size on screen`. If using a value other than -1, note that cropping may occur if your aspect ratio on screen does not match the aspect ratio defined here
`hiResWidth`	`By default, hi res screenshot 4096x4096. May specify a different width, or set to -1 to use size on screen`. If using a value other than -1, note that cropping may occur if your aspect ratio on screen does not match the aspect ratio defined here
`hiResHeight`	`By default, hi res screenshot 4096x4096. May specify a different height, or set to -1 to use size on screen`. If using a value other than -1, note that cropping may occur if your aspect ratio on screen does not match the aspect ratio defined here
`waterMarkPlugin`	Provide a watermark for your screenshot downloads
`downloadImagePlugins`	By default, we provide certain downloads (jpg and png). If you want to provide more/different types, use these plugins to add more.
`imageFilename`	By default, the downloaded image gets a filename of the sku; override this to provide a custom imageFilename

spin2d options

These options are applicable to the render view for 2d renders only, and live under spin2d, i.e.

const configurator = new MxtProductConfigurator.MxtKongfigurator({
    spin2d: {
        zoomDisabled: true
        ...
    },
});

Option Name	Option Description
`zoomDisabled`	Use this to disable zoom controls and not allow the user to look at a zoomed in (higher resolution) render
`backgroundColor`	`Default is white, format is {r:number, g:number, b:number, a:number} where each value goes from 0->1, inclusive`

Configurator Level Options

These options are applicable to the configurator in general and live at the root level of options

const configurator = new MxtProductConfigurator.MxtKongfigurator({
    assetEnvironment: MxtKongfigAssetEnvironment.STAGING
    ...
});

Option Name	Option Description
`renderType`	2d or 3d. Defaults to 3d.
`assetEnvironment`	`enum MxtKongfigAssetEnvironment { LATEST = "Latest", TEST = "Test", STAGING = "Stage", PRODUCTION = "Active" }` Use PRODUCTION for your production environment and STAGING for your cert environment, and TEST for your test enviroment. LATEST includes works-in-progress configurators and shouldn’t be used generally by clients.
`skuUrlParam`	`By default, we auto-update the URL parameter 'sku' with the current sku. Use this to change the url parameter to something other than 'sku'`
`initialSkus`	If you want to load a particular sku that is different than the default sku that a configurator model would naturally load
`colors?: { primary: IColor3; secondary: IColor3; dropShadow: IColor3; };`	Sets the primary color, secondary color, and drop shadow (used on certain buttons). Secondary color is used for the pricing, as well as the gradient color on the main CTA Many more color options can be set via css variables; see custom CSS section.
`backgroundColor`	Background color of the renderer only (not of the UI). Use any valid css string
`backgroundColorOnScreenshots`	Background color to use for screenshots; may be different than the normal background color
`baseShareUrl`	Ordinarily, for sharing, we share a link that points back to the current HTTP address of the page; override this to point to a custom page. Current URL search params are added to this url.
heading	Override the default camera heading in degrees, for 3d render type only
`pitch`	Override the default camera pitch in degrees, for 3d render type only
zoom	Override the default zoom, for 3d render type only
`showStepNumber`	By default, our UI does not show the step number next to steps; make this true to show step number
`icons`	{ sif?: string; sifInverse?: string; bom?: string; bomInverse?: string; crm?: string; crmInverse?: string; atc?: string; atcInverse?: string; share?: string; shareInverse?: string; virtualAssistantButton?: string; missing?: string; paginationFirst?: string; paginationLast?: string; paginationRight?: string; paginationLeft?: string; blocked?: string; info?: string; back?: string; help?: string; sectionArrow?: string; close?: string; alert?: string; searchIcon?: string; chevronDown?: string; stepGroupArrow?: string; }

Advanced Options, Plugins, and Callbacks

Plugins

There are number of different plugins available to override or add to Configurator.

Analytics: spinCommon.analyticsPlugin - Provide a custom analytics plugin; you would probably want to extends Kong3dSpinsAnalyticsPlugin or Kong2dSpinsAnalyticsPlugin depending on if it is a 2d or 3d render type.

All other plugins are passed in via spinCommon.plugins.

Plugins that are NOT provided by default:

KongPluginTypes.BOM - add a plugin that implements IConfiguratorBomPlugin and handles creating a bill of materials
KongPluginTypes.ATC - add a plugin that implements IConfiguratorAddToCartPlugin and handles adding to cart
KongPluginTypes.CRM - add a plugin that implements IConfiguratorCRMPlugin and handles doing CRM
PLUGIN_TYPE.CONFIG_PRICING - add a plugin that implements IConfiguratorPricingPlugin and handles doing CRM

Plugins that provide a default, but you may want to override:

RendererPluginType.SIF - add a plugin that extends SIFPlugin and provides custom behavior/SIF resolution
KongPluginTypes.HELP_ME_DECIDE - add a plugin that extends KongHelpMeDecidePlugin and provides custom UI for the help me decide modal
KongPluginTypes.OPTION_PAGE - add a plugin that extends OptionPagePlugin and provides custom UI for the options UI
KongPluginTypes.STEP_PAGE - add a plugin that extends StepPagePlugin and provides custom UI for the steps UI
KongPluginTypes.OPTION_POPOVER - add a plugin that extends OptionPopoverPlugin and provides custom UI for the tooltip on options

When creating a plugin, there is an id field that must be provided on the plugin (it is provided on all of our default plugins). If you want the same plugin to be used for every single configurator, use id = DEFAULT_PLUGIN_ID. If you want to use a different plugin for different configurators, then provide plugins with custom id fields, that match the plugin id field on the configurator model.

Custom Error Handling

callbacks?: {
    /** Allow for overriding of the error handling. Return false to prevent our default error handling, return true to continue our normal error handling */
    onError?: (e: PromiseRejectionEvent) => boolean;
};

By default, we handle errors by presenting an error modal to the user. If you want custom behavior, then override this method. To prevent our default modal, make sure you return false from the callback.

Custom Expand/Collapse

spinCommon: {
    expandButton?: {
        onExpand?: () => void;
        onCollapse?: () => void;
    };
},

The picker (if present) will automatically be hidden onExpand and restored onCollapse. However, if you want to take additional action on expand/collapse, hook into these callbacks

Components

By default, the configurator builds out all of the UI in the format below underneath the HTML element provided in the options:

However, we provide the ability for each UI components to be parented independently to best provide the needs for your custom UI. The list of components are:

Component Type	Component Typescript Class	Component CSS Class	Notes
`CombinedComponentType.PICKER_CONTAINER`	`PickerContainerComponent`	`.mxt-canvas-picker`	Contains the UI for picking steps/options, as well as the header/sku/pricing/etc (by default). Basically everything that isn’t the renderer
`CombinedComponentType.VIEWER_CONTAINER`	`ViewerContainerComponent`	`.mxt-configurator-viewer`	The container for the renderer. Contains both the renderer itself and the button bar for the renderer.
`CombinedComponentType.PICKER_SCROLLABLE`	`PickerScrollableComponent`	`.mxt-configurator-scrollable`	The scrollable section of the picker; see diagram above, depending on device contains different things.
`CombinedComponentType.MODALS`	`ModalComponent`	`.mxt-modal-container`	Container for all modals; by default overlays both the picker container and viewer container
`CombinedComponentType.VIEWER`	`ViewerComponent`	`.mxt-canvas-container`	Contains the actual renderer.
`CombinedComponentType.BUTTON_BAR`	`ButtonBarComponent`	`.mxt-spin-button-row`	Buttons for manipulating renderer (zoom/rotate/etc)
`CombinedComponentType.WEB_AR`	`WebArComponent`	`.mxt-webAr-container`	Button to trigger WebAR
`CombinedComponentType.ABOUT`	`AboutComponent`	`.mxt-about-button`	Button to trigger About modal
`CombinedComponentType.DOWNLOAD`	`DownloadButtonComponent`	`.mxt-btn-download`	Download screenshot button on button bar
`CombinedComponentType.DIMENSIONS`	`DimensionsButtonComponent`	`.mxt-btn-dimensions`	Toggle dimensions button on button bar
`CombinedComponentType.HOTSPOTS`	`HotspotButtonComponent`	`.mxt-btn-hotspot`	Toggle hotspots button on button bar
`CombinedComponentType.PRESET_VIEW`	`PresetViewButtonComponent`	`.mxt-btn-preset-view`	Show preset view modal button on button bar
`CombinedComponentType.EXPAND_BUTTON`	`ExpandButtonComponent`	`.mxt-btn-expand`	Expand/collapse renderer view
`CombinedComponentType.STEPS`	`StepsComponent`	`.mxt-configurator-steps`	Container to show steps; uses `StepPagePlugin` to build UI within it
`CombinedComponentType.OPTIONS`	`OptionsComponent`	`.mxt-configurator-options`	Container to show options; uses `OptionPagePlugin` to build UI within it
`CombinedComponentType.HEADER`	`HeaderComponent`	`.mxt-configurator-header`	Header label (name of configurator)
`CombinedComponentType.SUBHEADER`	`SubheaderComponent`	`.mxt-configurator-subheader`	Subheader label
`CombinedComponentType.SKU`	`HeaderSkuComponent`	`.mxt-configurator-header-sku`	Sku label
`CombinedComponentType.PRICING`	`PricingComponent`	`.mxt-configurator-total-pricing`	Pricing label
`CombinedComponentType.CTAS`	`CTAContainerComponent`	`.mxt-configurator-ctas`	CTA container
`CombinedComponentType.CTA_SHARE`	`ShareComponent`	`.mxt-configurator-cta-share`	Share button, only shows if enabled for configurator model
`CombinedComponentType.CTA_ATC`	`ATCComponent`	`.mxt-configurator-cta-atc`	Add to cart button, only shows if there is an Add to cart plugin
`CombinedComponentType.CTA_SIF`	`SIFComponent`	`.mxt-configurator-cta-sif`	SIF button, only shows if sif is enabled in app config
`CombinedComponentType.CTA_CRM`	`CRMComponent`	`.mxt-configurator-cta-crm`	CRM button, only shows if there is a crm plugin
`CombinedComponentType.CTA_BOM`	`BOMComponent`	`.mxt-configurator-cta-bom`	BOM button, only shows if there is a bom plugin

Customizing Component Locations

There is an option parentElements. This allows you to provide a different parent element for any given component type. You do not need to provide a parent element for each; you can pick and choose which ones you need to customize. For example, if you have your own section you want to put your CTAs, you could just provide:

parentElements: {
  ctas?: HTMLElement;
}

It is possible to provide custom parents for everything. However, a much more common use case is to just re-parent several smaller components (such as CTA_SHARE or WEB_AR). In that case, use both the spinCommon.element option to set the main parent over everything, and just define the parentElements that would not fall in their default location.

IF YOU DO NOT PROVIDE spinCommon.element (for example if you need to provide different parents for the picker container component and the viewer container component), then we will not create a root element to house everything else. This is a totally valid case, but If a root is not created, we cannot always automatically handle resize events. There are many edge cases where your parent elements may have been configured in a way that a resize event on one effects the size of the other. As a result, we turn off handling landscape vs portrait mode automatically. IF you believe you have a fairly standard setup, you may turn resizing back on via the option autoResizeAllParents.

Component parents may be updated at runtime via

  updateParentElement(key: string | SpinsComponentType | KongComponentType, newParent: HTMLElement, removeOldParent?: boolean): void {

  updateParentElements(newParentElements: MxtKongParentComponentOptions, removeOldParents?: Boolean): void {

Disabling Components

Components may be disabled via the option disabledComponents. It is possible to provide non-sensical situations, such as disabling the CTA container but not disabling the CTAs within it. An exception will be thrown in these cases.

In order to disable all picker components (for example if you are building the UI yourself and just using our MxtKongfigurator for the renderer), use the option disableAllPickerComponents.