Skip to main content

Configurator Inputs Schema

A configurator inputs schema aims to declare all the data that is required by the configurator to function. This data would ideally be different for each project/configurator that we deploy for our clients.

Here is a high level overview of what the primary properties of this schema are:

{
  "productData": {
    // All products which are to be a part of this configurator
  },
  "categoryData": {
    // Information mapping each product and the available variants to a section within the UI
    "build": [],
    "color": []
  },
  "lookData": {
    // Information related to every look available within the project. This is usually a set of data required to populate the UI.
  },
  "configuratorSettings": {
    // Contains all the settings related to the configurator's behaviour.
  },
  "hotspotsData":{
    // Contains information related to the hotspots that need to be spawned for a product in the scene. This is entirely optional.
  }, 
  "assetsData": {
    // Contains information related to the assets used within the project. For example, a CSS that needs to be loaded at runtime, icons to be used within the configurator, assets that will affect the mood of the scene, etc.
  }
}

Product Data (productData):​

Type: object

This object contains all information about every product that is being used in the configurator. Each entry (an object as well) within the productData object contains the below mentioned properties.

Here are the details about Product Data:

Product Data (single) Properties

  • name ( string ) Name of the SKU. This is what would be displayed on the thumbnails in the Build Tab.

  • followsParent ( boolean ) Whether this product will follow it's parent within the scene when the parent is dragged around.

  • disableInteraction ( boolean ) Disables all interaction on the product when spawned.

  • ignoreSpawningCollision (boolean): Sets whether the ghost from this sku should use collision detection while spawn or not

  • disableCollider (boolean): Sets whether after spawning the sku in the scene it will have a collider or not

  • excludeFromSceneBounds ( boolean ) Excludes all instances of the sku from the scene bounds calculation used for camera zoom level

  • gltfURL ( string ) URL where the renderGeo GLTF is available for this product. This property would mostly be filled out by Epigraph, unless the client is providing their own render geometries.

  • colliderProxyGLTF ( string ) This is the proxy mesh for this product. This is mostly an optimised version of the renderGeo provide in the gltfURL property.

  • defaultVariant ( string ) [ REQUIRED ]: The default variant that would be picked for this product. This name has to match one of the entries within the lookDetails property.

  • **ignoreGhostCollision ( boolean ) Sets whether on spawning this item should it ignore collision with other items in the scene.

  • lookDetails ( object ):

    Contains all the material variants for the product SKU as key, and every material variant contains all the information available for the Material Variants of the product SKU, Here are more details about lookDetails:

    • LookDetails (single) Properties
      • title ( string ): name of the product with this material variant.
      • description ( string ) [ REQUIRED ]: Used to populate product description in UI. Usually, right below the product title.
      • productPageUrl ( string ) [ REQUIRED ]: Link to the product SKU page on client's website
      • thumbnails ( object ) [ REQUIRED ]: Contains thumbnail image of the product SKU in different look (default will be used in case there is no look available)
      • price ( number ): Price of the current product.
      • clientProductId ( string ): An optional ID that would be returned in getCartItems() if provided.
    • LookDetails Object Example
       lookDetails: {
        red:{
          title: "26 in 4-Drawer",
          description: "Your multi-utility storage and changing solution",
          productPageUrl: "https://www.craftsman.com?id=red",
          thumbnails: {
            high:
              "<@all-projects@>/demo-project/thumbnails/tab-build/top01-red.png",
            low:
              "<@all-projects@>/demo-project/thumbnails/tab-build/top01-red.png",
          },
          price: 248, 
          clientProductId: "OTFC-1236"
        },
        black:{
          title: "26 in 4-Drawer",
          description: "Your multi-utility storage and changing solution",
          productPageUrl: "https://www.craftsman.com?id=black",
          thumbnails: {
            high:
              "<@all-projects@>/demo-project/thumbnails/tab-build/top01-black.png",
            low:
              "<@all-projects@>/demo-project/thumbnails/tab-build/top01-black.png",
          },
          price: 250, 
          clientProductId: "OTFC-4658"
        },
       },

  • plugs ( object[] ):

    This object is entirely optional and can be used to override the plug properties defined inside proxy, Here are the details about Plugs:

    • Plug (single) Properties
      • name ( string ): name of the plug object in the proxy model.
      • acceptedPlugTypes ( string[] ): ids of the plug that can be connected to this plug.
      • connectsToPlugTypes ( string[] ): ids of the plug this plug can connect to.
    • Plugs Object Example
       plugs: [
        {
          name: "out_1",
          acceptedPlugTypes: [],
          connectsToPlugTypes: ["67"],
        },
        {
          name: "in_1",
          acceptedPlugTypes: ["spraycanshelf"],
          connectsToPlugTypes: [],
        },
      ],
  • gltfURL ( string ): Link to the master product model gltf file, which contains internal links to mesh, texture, and looks.
  • colliderProxyGLTF ( string ): Link to the proxy model of the product SKU. Contains plugs and its transform. Contains bounding box/dimensions information
Product Data Object Example
"productsData": {
  "productSKU": {
    name: "Toolchest 67",
    defaultVariant: "red",
    disableInteraction: false,
    excludeFromSceneBounds:false,
    lookDetails: {
      red: {
        title: "26 in 4-Drawer",
        description:
          "Your multi-utility storage and changing solution, this S2000 26 in. 4-Drawer Tool Chest is optimally suited for stowing tools while keeping your batteries and electronics powered up.",
        productPageUrl:
          "https://www.craftsman.com/product/cmst98267rb/26-4-drawer-tool-chest-s2000?tid=569046",
        thumbnails: {
          high:
            "<@all-projects@>/demo-project/thumbnails/tab-build/top01-red.png",
          low:
            "<@all-projects@>/demo-project/thumbnails/tab-build/top01-red.png",
        },
        price: 248, 
        clientProductId: "OTFC-1236"
      },
      black: {
        title: "26 in 4-Drawer",
        description:
          "Your multi-utility storage and changing solution, this S2000 26 in. 4-Drawer Tool Chest is optimally suited for stowing tools while keeping your batteries and electronics powered up.",
        productPageUrl:
          "https://www.craftsman.com/product/cmst98267rb/26-4-drawer-tool-chest-s2000?tid=569046",
        thumbnails: {
          high:
            "<@all-projects@>/demo-project/thumbnails/tab-build/top02-black.png",
          low:
            "<@all-projects@>/demo-project/thumbnails/tab-build/top02-black.png",
        },
        price: 258, 
        clientProductId: "OTFC-4658"
      },
    },
    plugs: [
      {
        name: "toolchest67_out_plug01",
        acceptedPlugTypes: [],
        connectsToPlugTypes: ["67"],
      },
      {
        name: "toolchest67_spraycan_plug01",
        acceptedPlugTypes: ["spraycanshelf"],
        connectsToPlugTypes: [],
      }
    ],
    followsParent: false,
    gltfURL:
      "<@all-projects@>/demo-project/3d-assets/renderGeo/toolchest67/toolchest67.gltf",
    colliderProxyGLTF:
      "<@all-projects@>/demo-project/3d-assets/proxies/toolchest67_proxy.glb",
  }
}

Category Data (categoryData):​

Type: object

This object contains all information used for populating the Build and Color Tab in the UI.

A categoryData object consists of the following subparts:

{
  "build": [], // Showcases all available product SKUs
  "color": [] // Showcases all available looks
}
Category Data Object Example
categoryData: {
  build: [
    {
        label: "Tool Chest",
        replace: false,
        swappable: false,
        categoryID: "top",
        skus: ["Craftsman67", "Craftsman69", "Craftsman72"],
    },
    {
        label: "Tool Chest",
        replace: false,
        swappable: false,
        categoryID: "top",
        skus: ["Craftsman67", "Craftsman69", "Craftsman72"],
    }
  ],
  color: [
    {
      id: "exterior",
      label: "EXTERIOR",
      look: ["red", "black"],
    }
  ]
}

Build (build):​

This object contains build categories and its constituent product SKU IDs. Build Tab provides user with the functionality to add products to the 3D configurator and view more information about them.

Here are the details about Build Object:

Build Category (single) Properties
  • categoryID ( string ) [ REQUIRED ]: ID of the build category
  • label ( string ) [ REQUIRED ]: Name of the build category, that will be shown in the ui
  • replace ( boolean ): If true, the build category becomes replacaeble, meaning only one productSKU in this category can exist, if another is spawned it will replace the previous one in the scene. (the plugs for all the sku's in this category should match)
  • swappable ( boolean ): If true, the build category becomes swappable, meaning product SKU can be spawnned in new spots also have the ability to swap an existing sku in the scene with another (both replace and swappable can't be true at the same time)
  • skus ( string[] ) [ REQUIRED ]: Contains Product SKU IDs that are part of this category
Build Object Example
build: [
  {
      categoryID: "top",
      label: "Tool Chest",
      replace: false,
      swappable: false,
      skus: ["Craftsman67", "Craftsman69", "Craftsman72"],
  },
  {
      categoryID: "bottom",
      label: "Tool Cabinet",
      replace: false,
      swappable: false,
      skus: ["rolloutcabinet68", "rolloutcabinet70", "rolloutcabinet73"],
  }
]

Color (color):​

This object contains look categories and its constituent material variants. The Color tab provides user with the functionality to switch product's material variant in the 3D configurator.

Here are the details about Color Object:

Look Category (single) Properties
  • id ( string ) [ REQUIRED ]: ID of the look category that a group of looks belong to. For eg. "Oak", "Walnut", "Birch" looks could belong to the same category called "Wood". Category name could be anything.
  • label ( string ) [ REQUIRED ]: Name of the color category, that will be shown in the UI.
  • looks ( string[] ) [ REQUIRED ]: Name of the looks that are to be a part of this color category. For eg. ["Oak", "Walnut", "Birch"] etc.
Color Object Example
    color: [
      {
        id: "exterior",
        label: "EXTERIOR",
        looks: ["red", "black"],
      },
      {
        id: "interior",
        label: "INTERIOR",
        looks: ["grey", "silver"],
      }
    ]

Look Data (lookData):​

Type: object

This object contains all material variants available in the configurator. It contains all relevant information for a material variant like label, thumbnail, accent and more.

Here are the details about Look Data:

Material Variant (single) Properties
  • category ( string ): categoryID of the material variant
  • label ( string ) [ REQUIRED ]: Name of the material variant, that will be shown in the UI
  • accent ( string ): Accent of the material variant, that will be shown in the UI
  • thumbnail ( string ) [ REQUIRED ]: Link to the thumbnail, that will be shown in the UI
Look Data Object Example
"lookData": {
  red: {
    label: "Red",
    accent: "Cherry Accent",
    category: "exterior",
    thumbnail: "/img/ColorImages/red.png"
  },
  black: {
    label: "Black",
    accent: "Black Accent",
    category: "exterior",
    thumbnail: "/img/ColorImages/black.png"
  },
}

Configurator Settings (configuratorSettings):​

Type: object

This object contains all global scene level settings used by the configurator.

A configuratorSettings object consists of the following subparts:

{
  "cameraSettings": {}, // Defines settings assosciated with the scene camera.
  "coreSettings": {}, // Defines some core level settings of the configurator.
  "endpoints": {}, //Endpoints for core level functionality
}

Camera Settings (cameraSettings):​

This object contains initial settings for the scene camera in the configurator

Here are the details about Camera Settings Object:

Camera Settings Properties
  • initialViewPointPosition ( array ): Sets the Initial View Point Position of the camera when the configurator initializes
  • minPolarAngle ( number ): Sets the minimum polar angle of the camera
  • maxPolarAngle ( number ): Sets the maximum polar angle of the camera
  • minDistance ( number ): Sets how far you can dolly in
  • maxDistance ( number ): Sets how far you can dolly out
  • enableDamping ( boolean ): Set to true to enable damping (inertia), which can be used to give a sense of weight to the controls
  • dampingFactor ( number ): Sets the damping inertia used if enableDamping is set to true.
  • canAutoRotate ( boolean ): Set to true to automatically rotate around the target
  • autoRotateSpeed ( number ): Set how fast to rotate around the target if canAutoRotate is true. If the value is 1.0, it equates to 60 seconds per orbit at 60fps
  • camFar ( number ): Sets the camera far plane distance
  • camNear ( number ): Sets the camera near plane distance
  • fov ( number ): Sets the field of view of the camera
  • canPan ( boolean ): Sets whether camera can pan
  • canZoom ( boolean ): Sets whether camera can zoom in/out
  • zoomSpeed ( number ): Sets the zoom speed of the camera
  • rotateSpeed ( number ): Sets the rotation speed of the camera while orbiting
  • clearColour ( string ): Sets the background/Clear colour of the canvas
  • distanceMultiplier_mobile ( number ): Distance multiplier for the autofocus zoom in mobile
  • distanceMultiplierdesktop ( number ): Distance multiplier for the autofocus zoom in desktop
  • ghostColor ( object ): rgba color of the ghost for the project
Camera Settings Object Example
cameraSettings: {
  initialViewPointPosition: [5, 1, 2],
  minPolarAngle: 35,
  maxPolarAngle: 90,
  minDistance: 2,
  maxDistance: 5,
  enableDamping:true,
  dampingFactor:0.025,
  canAutoRotate:true,
  autoRotateSpeed:0.5,
  camFar: 250,
  camNear: 100,
  canPan: false,
  fov: 35,
  canZoom: true,
  zoomSpeed:0.5,
  rotateSpeed:0.5,
  clearColour: "#fcfbf7",
  distanceMultiplier_mobile: 1,
  distanceMultiplier_desktop: 1,
  ghostColor: {r: 255, g: 90, b: 0, a: 0.75}
}

Core Settings (coreSettings):​

This object contains global project level settings for the configurator

Here are the details about Core Settings Object:

Core Settings Properties
  • draggableUI ( boolean ): Sets the ability to the drag the thumbnail of the Default UI
  • swappableRoot ( boolean ): Sets whether root is allowed to be swapped to its neighbour
  • showReset_mobile ( boolean ): Sets the visibility for Reset button on mobile
  • showReset_desktop ( boolean ): Sets the visibility for Reset button on desktop
  • showDimension_mobile ( boolean ): Sets the visibility for Dimension button on mobile
  • showDimension_desktop ( boolean ): Sets the visibility for Dimension button on mobile
  • showSave_mobile ( boolean ): Sets the visibility for Save button on mobile
  • showSave_desktop ( boolean ): Sets the visibility for Save button on desktop
  • showShare_mobile ( boolean ): Sets the visibility for Share button on mobile
  • showShare_desktop ( boolean ): Sets the visibility for Share button on desktop
  • showContextMenu_mobile ( boolean ): Sets the visibility for Context Menu on mobile
  • showContextMenu_desktop ( boolean ): Sets the visibility for Context Menu on desktop
  • showViewInYourSpace_mobile ( boolean ): Sets the visibility for View In Your Space button on mobile
  • showViewInYourSpace_desktop ( boolean ): Sets the visibility for View In Your Space button on desktop
  • showDependencyOnHover (boolean): Sets the visibility for Dependency on hover of disabled thumbnails in Build UI
  • showHotspotsBtn_desktop ( boolean ): Sets the visibility for Show/Hide Hotspots button on desktop
  • showHotspotsBtn_mobile ( boolean ): Sets the visibility for Show/Hide Hotspots button on mobile
  • sceneScaleUnit ( string ): Sets the unit for the scene dimensions (m, cm, mm, ft, in)
  • disableDragDrop ( boolean ): Allows you to disable all drag and drop from within the canvas
  • disableContextMenu ( boolean ): Allows you to disable the context menu from within the canvas
  • currency ( string ): Sets the currency for the configurator
  • ignoreSpawningCollision (boolean): Sets globally whether the ghost should use collision detection while spawn or not
  • disableCollider (boolean): Sets globally whether after spawning the sku in the scene it will have a collider or not
  • ghostAsWireframe (boolean): Spawns the ghost as wireframe
  • preserveDrawingBuffer (boolean): Enable this for the projects where the client wishes to take a screenshot of the current view.
  • outOfStock_EmissiveColor (object): Sets the emissive color of the item to this value when its out of stock
  • outOfStock_EmissiveIntensity (number): Sets the emissive intensity of the item to this value when its out of stock
Core Settings Object Example
coreSettings: {
  draggableUI: false,
  swappableRoot: false,
  showReset_mobile: true,
  showReset_desktop: true,
  showDimension_mobile: true,
  showDimension_desktop: true,
  showSave_mobile: false,
  showSave_desktop: false,
  showShare_mobile: true,
  showShare_desktop: true,
  showContextMenu_mobile: false,
  showContextMenu_desktop: true,
  showViewInYourSpace_mobile: false,
  showViewInYourSpace_desktop: false,
  showDependencyOnHover: true,
  showHotspotsBtn_desktop:false,
  showHotspotsBtn_mobile:false,
  sceneScaleUnit: "cm",
  disableDragDrop:false,
  disableContextMenu:false,
  currency: "€",
  ignoreSpawningCollision:false,
  ghostAsWireframe:false, 
  preserveDrawingBuffer: false,
  outOfStock_EmissiveColor:{r:255,g:255,b:255},
  outOfStock_EmissiveIntensity:0.5
}

Endpoints (endpoints):​

Endpoints for core level functionality

Here are the details about endpoints Object:

Endpoints Properties
  • ASSETS_SOURCE_ROOT ( string ): Sets the visibility for Reset button on mobile
  • SAVE_CONFIG_ENDPOINT ( string ): Sets the visibility for Reset button on desktop
  • FETCH_CONFIG_ENDPOINT ( string ): Sets the visibility for Dimension button on mobile
  • PUBLIC_DESIGN_ASSETS_ENDPOINT ( string ): Sets the visibility for Dimension button on mobile
Endpoints Object Example
endpoints: {
  "ASSETS_SOURCE_ROOT":
    "https://storage.googleapis.com/epigraph-configurator",
  "SAVE_CONFIG_ENDPOINT":
    "https://store-structure-firebase-epigraph.glitch.me/saveConfig",
  "FETCH_CONFIG_ENDPOINT":
    "https://store-structure-firebase-epigraph.glitch.me?configID=",
  "PUBLIC_DESIGN_ASSETS_ENDPOINT":
    "https://storage.googleapis.com/gsc-epigraph-design/product-assets",
}

Here are the details about ConfiguratorSettings Object:

Configurator Settings Object Example
sceneData: {
  cameraSettings: {
    initialViewPointPosition: [5, 1, 2],
    minPolarAngle: 35,
    maxPolarAngle: 90,
    minDistance: 2,
    maxDistance: 5,
    enableDamping:true,
    dampingFactor:0.025,
    canAutoRotate:true,
    autoRotateSpeed:0.5,
    camFar: 250,
    camNear: 100,
    canPan: false,
    fov: 35,
    canZoom: true,
    zoomSpeed:0.5,
    rotateSpeed:0.5,
    clearColour: "#fcfbf7",
    distanceMultiplier_mobile: 1,
    distanceMultiplier_desktop: 1,
    ghostColor: {r: 255, g: 90, b: 0, a: 0.75}
  },
  coreSettings: {
    draggableUI: false,
    swappableRoot: false,
    showReset_mobile: true,
    showReset_desktop: true,
    showDimension_mobile: true,
    showDimension_desktop: true,
    showSave_mobile: false,
    showSave_desktop: false,
    showShare_mobile: true,
    showShare_desktop: true,
    showContextMenu_mobile: false,
    showContextMenu_desktop: true,
    showViewInYourSpace_mobile: false,
    showViewInYourSpace_desktop: false,
    showHotspotsBtn_desktop:false,
    showHotspotsBtn_mobile:false,
    sceneScaleUnit: "cm",
    disableDragDrop:false,
    disableContextMenu:false,
    currency: "€",
    ignoreSpawningCollision:false, 
    ghostAsWireframe:false,
    preserveDrawingBuffer: false
  },
  endpoints: {
    ASSETS_SOURCE_ROOT:
      "https://storage.googleapis.com/epigraph-configurator",
    SAVE_CONFIG_ENDPOINT:
      "https://store-structure-firebase-epigraph.glitch.me/saveConfig",
    FETCH_CONFIG_ENDPOINT:
      "https://store-structure-firebase-epigraph.glitch.me?configID=",
    PUBLIC_DESIGN_ASSETS_ENDPOINT:
      "https://storage.googleapis.com/gsc-epigraph-design/product-assets",
  }
},

Hotspots Data (hotspotsData):​

Type: object

This contains all the hotspots that needs to be displayed for the any product SKU in our 3D viewer.

Each entry (object) within the hotspots object is a product SKU which contains all the hotspots present in that SKU:

Hotspot Data Object Example
"hotspotsData": {
  "productSku1": [
    {
      //hotspot A object for productSku1
    }
    ,
    {
      //hotspot B object for productSku1
    }
  ],
  "productSku2": [
    {
      //hotspot C object for productSku2
    }
    ,
    {
      //hotspot D object for productSku2
    }
  ]
}
  • Hotspots (single) Properties
    • hotspotID (string): A unique identifier for this Hotspot.
    • categoryID (string): A unique category identifier for this Hotspot.
    • title (string) [ REQUIRED ]: Title of the hotspot.
    • description (string) [ REQUIRED ]: Represents the feature description shown in UI upon clicking the hotspot.
    • entryAnim (string): Animation name in the glb that needs to be played on hotspot enter (plays once on visit).
    • activeAnim (string): Animation name in the glb that needs to be played while hotspot is active (plays on loop till exit).
    • exitAnim (string): Animation name in the glb that needs to be played while exiting the hotspot (plays once on exit).
    • carousel (object[]) [ REQUIRED ]: Used to populate the product Features Tab (Supports image, svg, gif, and video).
      • type (string) [ REQUIRED ]: possibile inputs ["img","video"].
      • link (string) [ REQUIRED ]: link to image or video content.
      • alt (string) : alternate text to show instead of image or video content, if it fails to load.
    • hotspotPointTransform (object): Respresents the location of the hotspot with respect the product SKU.
    • viewPointTransform (object): Represents the camera's viewpoint location when the hotspot is click.
    • focusPointTransform (object): Represents the position where camera will focus upon clicking the hotspot.
  • Hotspots (single) Object Example
    {
        hotspotID: "hotspot01", // Hotspot ID
        categoryID: "power", // Hotspot ID
        title: "26 in 4-Drawer Tool Chest (S2000)", // Title of the hotspot
        description: "Hotspot Description", // Represents the feature description shown in UI upon clicking the hotspot
        entryAnim: "", // Animation name in the glb that needs to be played on hotspot enter (plays only once per visit)
        activeAnim: "", // Animation name in the glb that needs to be played while hotspot is active (plays on loop till exit)
        exitAnim: "", // Animation name in the glb that needs to be played while exiting the hotspot (plays once on exit)
        carousel: [
          {
            type: "img",
            link: "https://www.craftsman.com/NAG/PRODUCT/IMAGES/HIRES/CMST98267RB/CMST98267RB_1.jpg",
            alt: "Image"
          }
        ],
        hotspotPointTransform: {
          position: [0.1, 0.3, 0.2],
        },
        viewPointTransform: {
          position: [1, 1.5, 2.0],
        },
        focusPointTransform: {
          position: [0.244818, 0.848637, 0.709813],
        },
      }

Assets Data (assetsData):​

Type: object

This contains information related to the assets used within the project. For example, a CSS that needs to be loaded at runtime, icons to be used within the configurator, assets that will affect the mood of the scene, etc.

Here are the details about assetsData Object:

Assets Data Object Example
"hotspotsData": {
  "uiStyles": [
    {
      "id": "ui-variables",
      "url": "<@all-projects@>/demo-project/styles/variables.css",
      "enabled": true,
    },
    {
      "id": "override",
      "url": "<@all-projects@>/demo-project/styles/override.css",
      "enabled": false,
    },
  ],
  "coreStyles": [
    {
      "id": "core-variables",
      "url": "<@all-projects@>/demo-project/styles/variables.css",
      "enabled": true,
    },
  ],
}
Assets Data Properties
  • uiStyles (object[]) [ REQUIRED ]: Used to populate the product Features Tab (Supports image, svg, gif, and video).
    • id (string) [ REQUIRED ]: Assigns the script an id
    • url (string) [ REQUIRED ]: URL to the script
    • enabled (boolean) [ REQUIRED ]: Allows the script to be loaded into the configurator
  • coreStyles (object[]) [ REQUIRED ]: Used to populate the product Features Tab (Supports image, svg, gif, and video).
    • id (string) [ REQUIRED ]: Assigns the script an id
    • url (string) [ REQUIRED ]: URL to the script
    • enabled (boolean) [ REQUIRED ]: Allows the script to be loaded into the configurator