Configurator API

The client-side configurator API contains functions for retrieving and setting the product attribute values and can be accessed from the player API, which in turn is the result of the promise returned when embedding the player.

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.

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})

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"
    }, 
]
});