Configurator Core API Reference

Complete reference for the ConfiguratorCoreAPI class -- the primary interface for controlling the Epigraph Configurator web component programmatically

Accessing the API

The Core API is a singleton exposed on the web component element. Wait for the coreApi:ready event before calling any methods.

const configurator = document.getElementById("wcEpigraphConfigurator");

configurator.addEventListener("coreApi:ready", () => {
  const coreApi = configurator.api.core;
  // API is ready to use
});

Properties

PropertyTypeWritableDescription
isReadybooleanNoWhether the Core API is initialized and ready for use
categoryDataobjectNoAll category information for loaded products
productDataobjectNoFull product dataset used by the configurator
lookDataobjectNoAll look/appearance data for loaded products
hotspotsDataobjectNoFull hotspot data used by the configurator
sceneSettingsobjectNoScene settings provided via configurator inputs
assetsDataobjectNoAsset information for loaded products
isMobilebooleanNoWhether the current device is mobile
isScreenPortraitbooleanNoWhether the screen orientation is portrait
hasSceneChangedbooleanYesWhether the scene has changed since the last save
EVENTSobjectNoType-safe event name constants (see Events)

Methods

Asset Resolution

getResolvedAssetUrl(url)string

Resolves a relative asset path from the API to its full URL. Use this for all asset paths returned by productData (e.g. thumbnail paths).

ParameterTypeDescription
urlstringRelative asset path

Scene Management

clearScene()

Removes all items from the scene.

restartScene()

Resets the scene to its initial state (shared configuration or empty).

getSceneItems()object

Returns the current items in the scene, or undefined on error.

getSceneItemCount()number

Returns the number of items currently in the scene, or undefined on error.

getSceneStructure()object

Returns the complete scene configuration as a JSON object. The returned structure can be passed to loadSceneFromConfiguration() to restore the scene.

getSceneStructureRaw()object

Returns the raw scene structure without any processing.

getAllConnectionsInScene()Map

Returns all structure connections in a map for debugging purposes.

loadSceneFromConfiguration(structureToLoad)

Loads a scene from a JSON configuration object.

ParameterTypeDescription
structureToLoadobjectA scene structure object (as returned by getSceneStructure())

loadSceneFromConfigurationID(idToLoad, updateDefaultStructure)

Loads a scene from a configuration stored in Epigraph's database.

ParameterTypeDefaultDescription
idToLoadstringThe configuration ID
updateDefaultStructurebooleantrueWhether the loaded configuration becomes the default when restarting the scene

getSceneAsGlbUrl()string

Returns a blob URL containing the current scene as a GLB file. Results are cached until the scene changes.

getSceneAsUsdzUrl()string

Returns a blob URL containing the current scene as a USDZ file. Results are cached until the scene changes.


Spawning and Removing Items

spawnItemBySkuID(skuId, spawnGhostsFirst)object

Spawns an item into the scene. Only SKU IDs present in productData are valid.

ParameterTypeDefaultDescription
skuIdstringA valid product SKU identifier
spawnGhostsFirstbooleanfalseIf true, show ghost previews before placing

Returns the spawned item's GUID.

spawnItemBySkuIDAndGhostIndex(skuId, ghostIndex)object

Spawns an item using an already-spawned ghost at the given index.

ParameterTypeDefaultDescription
skuIdstringA valid product SKU identifier
ghostIndexnumber0The index of the ghost to use for placement

Returns the spawned item's GUID, or null if the index is invalid.

forceSpawnItem(skuId, guid)

Spawns an item at the root level of the scene.

ParameterTypeDescription
skuIdstringProduct identifier
guidstringInstance identifier

removeItemByGUID(guid, force)

Removes the item matching the provided GUID from the scene.

ParameterTypeDefaultDescription
guidstringItem instance identifier
forcebooleanfalseIf true, skips root-swapping logic

removeSelectedItem()object

Removes the currently selected item. Returns the deleted item data, or null if nothing is selected.

replaceItemBySkuId(guid, skuId)object

Replaces a specific item in the scene with a different SKU. Only works if all plugs are compatible between both SKUs.

ParameterTypeDescription
guidstringGUID of the item to replace
skuIdstringSKU ID of the replacement item

replaceItemsBySkuId(guids, skuId)boolean

Replaces multiple items in the scene with the same SKU. Only works if all plugs are compatible between both SKUs.

ParameterTypeDescription
guidsstring[]Array of GUIDs of items to replace
skuIdstringSKU ID of the replacement item

Returns true if all replacements succeed. Throws an error if any replacement fails.

replaceAllItemsBySkuId(replaceSkuId, newSkuId)boolean

Replaces all items of a particular SKU in the scene with a different SKU. Only works if all plugs are compatible between both SKUs.

ParameterTypeDescription
replaceSkuIdstringSKU ID of items to replace
newSkuIdstringSKU ID of the replacement item

Returns true if all replacements succeed.

getSpawningRequirementForSkuID(skuID)array

Returns an array of prerequisite SKU IDs required before the given SKU can be spawned.

ParameterTypeDescription
skuIDstringProduct identifier

getAllSkusThatCanReplaceGuid(guid)array

Returns an array of SKU IDs that can replace the item with the given GUID.

ParameterTypeDescription
guidstringItem instance identifier

getFittingSkuIds()array

Returns SKU IDs that are compatible with the current scene configuration.

updateFittingSkuIds()

Manually triggers a recalculation of fitting SKU IDs.

triggerItemRemoveModal(guid)

Fires the EVENTS.SCENE.ItemRemoveModalTriggered event with information about the item and its dependencies, allowing you to show a custom removal confirmation dialog.

ParameterTypeDescription
guidstringGUID of the item to remove

Ghost Previews

spawnGhostsForSkuID(skuId, ignoreCollision, count)

Displays ghost (semi-transparent) previews showing where an item can be placed.

ParameterTypeDefaultDescription
skuIdstringProduct identifier
ignoreCollisionbooleanfalseWhether to ignore collision detection
countnumberNumber of ghost previews to show

removeAllGhosts()

Removes all ghost previews from the scene.

getActiveGhostData()object

Returns data about the currently spawned ghosts, or null if no ghosts are active.


Drag and Drop

itemDragStart(skuId)

Activates drag mode for the given SKU. Call this when a thumbnail drag enters the configurator canvas. Automatically spawns ghost previews.

ParameterTypeDescription
skuIdstringProduct identifier being dragged

itemDragEnd()

Deactivates drag mode. If the cursor is over a valid ghost position, the item is placed. Otherwise, ghosts are removed. Call this when the drag leaves the canvas or the user releases.


Selection and Interaction

selectItemWithGUID(guid)

Programmatically selects an item in the scene for material customization or inspection.

ParameterTypeDescription
guidstringItem instance identifier

exitSelectedItem()

Clears the current item selection.

getSelectedItemData()object

Returns attribute data for the currently selected item, or null if nothing is selected.

rotateItemByGUID(guid)

Rotates the item with the given GUID.

rotateSelectedItem()object

Rotates the currently selected item. Returns the rotated item data, or null if nothing is selected.

canSelectedItemRotate()boolean

Returns whether the currently selected item supports rotation.

canSelectedItemBeRemoved()boolean

Returns whether the currently selected item can be removed.

canSelectedItemDrag()boolean

Returns whether the currently selected item supports dragging.

doesGuidItemHaveAnAttachedDependency(guid)boolean

Returns whether the item with the given GUID has other items attached to it as dependencies.

ParameterTypeDescription
guidstringItem instance identifier

getGuidItemAttachedDependencies(guid)object

Returns data for all items attached as dependencies to the given GUID. Useful for showing a removal confirmation dialog.

ParameterTypeDescription
guidstringItem instance identifier

doesSelectedItemHasAttachedDependency()boolean

Returns whether the currently selected item has attached dependencies.

isSelectedItemAnEndNode()boolean

Returns whether the currently selected item is a terminal node (no outgoing plugs).


Materials and Variants

switchGlobalVariant(lookCategory, lookVariant)

Changes the active material variant for an entire look category across all items in the scene.

ParameterTypeDescription
lookCategorystringCategory name (e.g. "wood", "hardware")
lookVariantstringVariant name (e.g. "walnut", "black")

switchGlobalGeometryVariant(geometryCategory, geometryVariant)

Changes the active geometry variant for an entire geometry category across all items in the scene.

ParameterTypeDescription
geometryCategorystringGeometry category name
geometryVariantstringGeometry variant name

overrideSelectedItemMaterial(colorID)

Applies a material override to the currently selected item.

ParameterTypeDescription
colorIDstringA valid variant identifier

overrideItemMaterialByGuid(guid, colorID)

Applies a material override to a specific item by its GUID.

ParameterTypeDescription
guidstringItem instance identifier
colorIDstringA valid variant identifier

getSelectedItemColors()array

Returns the available color/variant options for the currently selected item.

removeAllVariantOverrides()

Clears all material overrides from the scene, reverting to global variant defaults.


Context Menu

closeContextMenu()

Programmatically closes the active context menu and deselects the item.


Camera

getCurrentCameraDetails()object

Returns the complete camera state including position, rotation, and focus point.

moveCamera(viewPointPosition, focusPointPosition, resetToLastPosition)

Moves the camera to a specific view point and focus point position.

ParameterTypeDefaultDescription
viewPointPositionarrayCamera position as [x, y, z]
focusPointPositionarrayFocus point as [x, y, z]
resetToLastPositionbooleantrueWhether to return to the previous camera position when exiting
// Example: Move camera to look at the scene from above
coreApi.moveCamera([1, 2, 2], [0, 0, 0], false);

setCameraFocusPointPosition(focusPointPosition)

Manually sets the camera's focus point.

ParameterTypeDescription
focusPointPositionobjectA Vector3 object: { x, y, z }

getCameraFocusPointPosition()object

Returns the current focus point as a { x, y, z } object.

getCanvasSize()object

Returns the dimensions of the 3D canvas.


Environment

setEnvLightMap(newEnvMap)

Changes the scene's environment/lighting map.

ParameterTypeDescription
newEnvMapstringURL of the new environment map

getCurrentSceneEnvMap()string

Returns the URL of the currently active environment map.


Screenshots

getScreenshotForCurrentCamera(imgSize)string

Captures the current view as a base64-encoded image URL.

ParameterTypeDefaultDescription
imgSizeobjectCanvas sizeImage dimensions, e.g. { width: 128, height: 128 }

getScreenshotForCamera(camSettings, imgSize)string

Captures a screenshot from a specific camera position.

ParameterTypeDefaultDescription
camSettingsobjectCamera settings, e.g. { position: Vector3, rotation: Vector3 }
imgSizeobjectCanvas sizeImage dimensions, e.g. { width: 128, height: 128 }

getAllPredefinedScreenshots(imgSize)array

Captures screenshots from all predefined camera positions configured in the scene settings. Returns an array of base64-encoded image URLs.

ParameterTypeDefaultDescription
imgSizeobjectCanvas sizeImage dimensions, e.g. { width: 128, height: 128 }

Dimensions and Hotspots

areDimensionsVisible()boolean

Returns whether dimension overlays are currently shown.

getCurrentDimensions()object

Returns the bounding box information for the entire scene.

showDimensions()

Shows dimension overlays on the scene.

hideDimensions()

Hides dimension overlays.

areHotspotsVisible()boolean

Returns whether hotspots are currently visible.

areHotspotsTemporarilyVisible()boolean

Returns the temporary visibility state of hotspots (distinct from the global setting).

showAllHotspots(temporary)

Shows all hotspots in the scene.

ParameterTypeDefaultDescription
temporarybooleanfalseIf true, visibility is temporary and separate from the global state

hideAllHotspots(temporary)

Hides all hotspots in the scene.

ParameterTypeDefaultDescription
temporarybooleanfalseIf true, hides temporarily without changing the global state

getActiveHotspot()object

Returns the currently active hotspot, if any.

clickHotspot(domID)

Programmatically activates a hotspot by its DOM ID.

ParameterTypeDescription
domIDstringDOM element ID of the hotspot

exitHotspot()

Deactivates the currently active hotspot.


AR and Sharing

viewInYourSpace()

Launches an AR session, allowing users to place the configured product in their physical environment. Includes device capability detection.

shareScene()string

Generates and returns a shareable URL for the current configuration.

generateShareableLink(viewInYourSpaceLink)string

Returns a shareable URL with the configuration ID appended.

ParameterTypeDefaultDescription
viewInYourSpaceLinkbooleanfalseIf true, adds AR launch parameters to the URL

Cart and Commerce

enableCart()

Activates shopping cart functionality.

disableCart()

Deactivates shopping cart functionality.

getCartItemsAsync()object

Returns the current cart contents asynchronously.

checkoutAsync(forceCheckout)object

Clears the scene, fires EVENTS.SCENE.Cart_Checkout, and returns the cart items. If any items are out of stock and forceCheckout is false, fires EVENTS.SCENE.Cart_OutOfStock instead.

ParameterTypeDefaultDescription
forceCheckoutbooleanfalseIf true, bypasses stock validation

reloadCheckedoutScene()

Restores the scene and repopulates the cart with items from the last checkout.

setCartMessage(msg)

Displays a message in the cart (e.g. lead times, promotions). Fires EVENTS.SCENE.CartMessage_Update.

ParameterTypeDescription
msgstringThe message to display

getCurrentItemsInReplaceableCategory()object

Returns the selected items within replaceable categories.

getCartItems()object (deprecated)

Deprecated: Use getCartItemsAsync() instead.

Returns the current cart contents synchronously.

checkout(forceCheckout)object (deprecated)

Deprecated: Use checkoutAsync() instead.

Synchronous version of checkoutAsync().


Pricing and Inventory

getCurrentPricingInfo()object

Returns all products with their variants and current prices.

getCurrentCompareAtPricingInfo()object

Returns all products with their variants and compare-at prices.

updatePricingForAllProducts(newPricingObj)object

Updates pricing for all products at once. Returns updated pricing info.

ParameterTypeDescription
newPricingObjobjectPricing data keyed by SKU and variant

updatePricingForAllProductsAsync(newPricingObj)object

Async version of updatePricingForAllProducts().

updatePricingForProduct(skuId, materialVariant, newPrice)object

Updates the price for a single product-variant combination. Returns updated pricing info.

ParameterTypeDescription
skuIdstringProduct identifier
materialVariantstringVariant name
newPricestringNew price value

updatePricingForProductAsync(skuId, materialVariant, newPrice)object

Async version of updatePricingForProduct().

updateCompareAtPricingForAllProducts(newPricingObj)object

Updates compare-at pricing for all products. Returns updated compare-at pricing info.

ParameterTypeDescription
newPricingObjobjectCompare-at pricing data keyed by SKU and variant

updateCompareAtPricingForAllProductsAsync(newPricingObj)object

Async version of updateCompareAtPricingForAllProducts().

updateCompareAtPricingForProduct(skuId, materialVariant, newPrice)object

Updates the compare-at price for a single product-variant combination.

ParameterTypeDescription
skuIdstringProduct identifier
materialVariantstringVariant name
newPricestringNew compare-at price value

updateCompareAtPricingForProductAsync(skuId, materialVariant, newPrice)object

Async version of updateCompareAtPricingForProduct().

getInventoryInfo()object

Returns all products with their inventory quantities.

updateInventoryForAllProducts(updatedInventoryObj)object

Updates inventory for all products. Returns updated inventory info.

ParameterTypeDescription
updatedInventoryObjobjectInventory data keyed by SKU and variant

Preconfiguration

getPreconfigurationModuleData()object

Returns the data of the preconfiguration module present in the Build Tab, or undefined if preconfiguration doesn't exist.


Analytics

initializeAnalytics(analyticsIdentifiers, isDevEnvironment)

Sets up Epigraph Analytics. Overrides any existing analytics instance.

ParameterTypeDefaultDescription
analyticsIdentifiersobjectObject with gaMeasurementId and optionally epgExperienceID
isDevEnvironmentbooleanfalseWhether running in development mode

sendAnalyticsPageViewedEvent()

Sends a "Page Viewed" event to all active analytics platforms.

sendAnalyticsEvent(eventData)

Sends a custom analytics event.

ParameterTypeDescription
eventDataAnalyticsEventCustom event object

Utility

fireEvent(name, payload)

Dispatches a custom event on the configurator web component element.

ParameterTypeDescription
namestringEvent name
payload*Event data

setEmptySceneText(text)

Sets the text displayed when the scene is empty.

ParameterTypeDescription
textstringDisplay text

alert(options)

Shows a non-blocking alert within the configurator.

ParameterTypeDefaultDescription
options.alertMsgstringMessage content
options.alertTimenumberDisplay duration in milliseconds
options.alertTypestringAlert classification (e.g. "success")
options.alertLabelstringAlert title
options.persistantbooleanfalseWhether the alert icon persists after timeout
options.alertIdstringUnique identifier for the alert
coreApi.alert({
  alertMsg: "Configuration saved successfully.",
  alertTime: 3000,
  alertType: "success",
  alertLabel: "Saved",
  alertId: "configSaved",
});

removePersistantAlert()

Removes any persistent alert from the scene.

showInstructions()

Opens the instructions modal. Fires EVENTS.UI.Instructions_Show.

isSystemBusy()boolean

Returns whether the system is currently processing a previous action. Useful for preventing duplicate operations.

getDeviceState()object

Returns the current device state information.

isIosDevice()boolean

Returns whether the current device is running iOS.


Events

Lifecycle Events

These events are listened for directly on the web component element using string names:

EventDescription
coreApi:readyThe Core API has initialized successfully
coreApi:failedThe Core API failed to initialize
configurator.addEventListener("coreApi:ready", () => { /* ... */ });

Preload Events

These string-based events track asset loading progress. Useful for building a custom loading indicator.

EventDescription
preload:beginAsset preloading has started
preload:updatePreloading progress update (carries a progress percentage, 0--100)
preload:endAsset preloading is complete

Core Events (Type-Safe)

All other events are accessed via the EVENTS object on the Core API. This avoids string literals and lets your editor catch typos.

configurator.addEventListener(
  coreApi.EVENTS.UI.ContextMenu_Show,
  (event) => { /* ... */ }
);

UI Events

AccessorInternal ValueDescription
EVENTS.UI.PreloadScreen_Showpreload:showLoading screen should be shown
EVENTS.UI.PreloadScreen_Hidepreload:hideLoading screen should be hidden
EVENTS.UI.ContextMenu_ShowcontextMenu:showAn item was clicked; show the context menu
EVENTS.UI.ContextMenu_HidecontextMenu:hideThe context menu should be dismissed
EVENTS.UI.ContextMenu_InfoBtnClickedinfoButtonClicked_ContextMenuInfo button in context menu was clicked
EVENTS.UI.UtilityMenu_ShowutilityMenu:showUtility menu should be shown
EVENTS.UI.UtilityMenu_HideutilityMenu:hideUtility menu should be hidden
EVENTS.UI.ShareButton_ShowshareButton:showShare button should be shown
EVENTS.UI.ShareButton_HideshareButton:hideShare button should be hidden
EVENTS.UI.ViewInYourSpaceButton_ShowviewInYourSpace:showAR button should be shown
EVENTS.UI.ViewInYourSpaceButton_HideviewInYourSpace:hideAR button should be hidden
EVENTS.UI.ResetButton_ShowresetBtn:showReset button should be shown
EVENTS.UI.ResetButton_HideresetBtn:hideReset button should be hidden
EVENTS.UI.DimensionsButton_ShowdimensionsBtn:showDimensions button should be shown
EVENTS.UI.DimensionsButton_HidedimensionsBtn:hideDimensions button should be hidden
EVENTS.UI.Instructions_Showinstructions:showInstructions modal should be shown
EVENTS.UI.ReviewCart_Shownreview-cart-shownThe review cart panel was shown
EVENTS.UI.ReviewCart_Hiddenreview-cart-hiddenThe review cart panel was hidden

Scene Events

AccessorInternal ValueDescription
EVENTS.SCENE.Item_Addeditem:addedAn item was added to the scene
EVENTS.SCENE.Item_Removeditem:removedAn item was removed from the scene
EVENTS.SCENE.Items_Updateditems:updatedItem data was updated
EVENTS.SCENE.FittingSkuIds_UpdatedfittingSkuIds:updatedCompatible SKU IDs were recalculated
EVENTS.SCENE.CartItems_UpdatedcartItems:updatedCart contents changed
EVENTS.SCENE.Hotspot_Enterhotspot:enterUser entered a hotspot
EVENTS.SCENE.Hotspot_Exithotspot:exitUser exited a hotspot
EVENTS.SCENE.SavedConfiguration_Loadedloaded-saved-configurationA saved configuration was loaded
EVENTS.SCENE.MaterialOverrides_ExistsmaterialOverrideExistsA material override was applied
EVENTS.SCENE.Cart_Checkoutcart:checkoutCheckout was initiated
EVENTS.SCENE.Cart_OutOfStockcart:outOfStockCheckout blocked due to out-of-stock items
EVENTS.SCENE.Cart_StatusUpdatedcart:statusUpdatedCart status was updated
EVENTS.SCENE.ReplaceableCategory_UpdatedreplaceableCategory:updatedA replaceable category was changed
EVENTS.SCENE.GlobalVariant_UpdatedglobalVariant:updatedA global material variant was switched
EVENTS.SCENE.CategoryData_UpdatedcategoryData:updatedCategory data was updated
EVENTS.SCENE.GlobalGeometryVariant_UpdatedglobalGeometryVariant:updatedA global geometry variant was switched
EVENTS.SCENE.Ghost_Loadedghost:loadedGhost previews finished loading
EVENTS.SCENE.Model_Loadedmodel:loadedA 3D model finished loading
EVENTS.SCENE.Model_Removedmodel:removedA 3D model was removed
EVENTS.SCENE.Scene_Clearedscene:clearedThe scene was cleared
EVENTS.SCENE.Inventory_Updatedinventory:updatedInventory data was updated
EVENTS.SCENE.DraggingOnDrop_CollisionDetecteddraggingOnDrop:collisionDetectedA collision was detected during drag-and-drop
EVENTS.SCENE.ItemRemoveModalTriggereditemRemoveModal:triggeredItem removal confirmation was requested
EVENTS.SCENE.ActionButton_ClickedactionButton:clickedAn action button was clicked
EVENTS.SCENE.CartMessage_UpdatecartMessage:updatedCart message was updated

Configuration Events

AccessorInternal ValueDescription
EVENTS.CONFIGURATION.OnClickItemonClickItemAn item was clicked in the scene
EVENTS.CONFIGURATION.CameraDetails_UpdatecameraDetails:UpdateCamera details were updated

Further Reading