Configurator API

Initialize the Configurator

Threekit's Configurator API is initialized by calling player.getConfigurator()
This can be initialized at anytime but typically it's initialized with the player and stored somewhere for later use.

async function init() {
  const player = await window.threekitPlayer({
    assetId: "079838d8-60e9-40d8-93a8-6af73c255bef",
    authToken: "00000000-0000-0000-0000-000000000000",
    el: document.getElementById("player-el"),
  });

  window.player = player;
  window.configurator = await player.getConfigurator();
}

init();

Prefetch Attributes

Prefetches all images for attributes specified to improve loading performance (only applies to 2D player).

const configurator = await player.getConfigurator();
await configurator.prefetchAttributes(['Rotation'])

Get Attributes

Returns an array of attribute objects. This object contains defaultValue, id, name, type and an array of values for that attribute.

configurator.getAttributes()

returns:

[
 {
   id: "d5ed540b-4852-4da2-8134-0c96c347df6e",
   type: "Asset",
   name: "Front Cover Color",
   blacklist: [],
   assetType: "item",
   values: [
      {
       assetId: "0126ce54-5bd8-4f37-b83b-d00db596750c",
       name: "Matte Blue",
       tags: ["luggage-matte"],
       metadata: {},
       fileSize: null,
       label: "Matte Blue",
       visible: true,
       enabled: true
     },...
 },...
]

Get Display Attributes

Returns all visible attributes and their associated data to make integrations easier and more robust. For example, attribute tags and metadata are now returned to build better configuration experiences, like attribute option groupings and styles. Using includeHidden and enabledOnly boolean options, you can also return hidden or disabled attributes.

configurator.getDisplayAttributes();

returns:

[
 {
  id: "40670f6a-4faa-4d7c-9db5-bf1492f72aff",
  type: "Color",
  name: "Color",
  defaultValue: "#84f542",
  visible: true,
  enabled: true,
  hiddenValues: [],
  disabledValues: [],
  values: ["#84f542", "#FFFFFF"],
  value: "#84f542"
 }...
]

Get Configuration

Returns the current configuration for the product as an object containing Attribute/Value pairs.

player.configurator.getConfiguration()

returns:

{ 
      [attributeName]: "atributeValue",
      ....
}

Set Configuration

Sets product configuration using a Configuration Object as parameter. Can assign one or multiple attributes within the same call.

configurator.setConfiguration({attrName: attrValue})

Stage Configurator

In the case you need to get/set the attributes on the stage you have associated with your Threekit item, you will initialize it similarly to the configurator API and you can use the same methods listed above:

const stageConfigurator = await player.getStageConfigurator();

Attribute Types

It's worth mentioning the difference between primitive values & part reference values. Primitive values (e.g. String, Number, etc) are straightforward.

Primitive

configurator.setConfiguration({ "Color Attribute": "Red" });

However, reference attributes (e.g. materials, parts, etc.) receive the id of the Threekit Item/Asset. For example, to set the Wheels attribute in this example, we need to pass the id of the Wheel Item as the value.

Part References

configurator.setConfiguration({
  "Wheels Attribute": { assetId: "26e0c72c-77a2-4fae-a81d-c995e32187f2" }
});

Arrays

configurator.setConfiguration({
  "Items Attribute": [ 
    { 
     assetId: "26e0c72c-77a2-4fae-a81d-c995e32187f2", 
     configuration:{},
     type: "model"
    }, 
    { 
     assetId: "26e0c72c-abcd-456-a81d-c995e32187f2", 
     configuration:{},
     type: "model"
    }, 
]
});