Interacting with the Attributes through the Threekit Javascript API

Overview

Once the player has been initialized in a webpage using the following guide - embedding the Threekit Player, you should see the Threekit player load up your initial configuration as defined in your Organization on the Threekit platform.

From there we can use the Threekit API to get the Configurator for the item we have initialized the player with. The item’s configurator is how we interact with the Attributes for that item, where we follow a simple loop of using the Configurator to get the Attributes dataset, presenting them to the user, and subsequently passing their selection on to the Configurator for it to be applied.

Code Examples

You will need the following commands to achieve this.

The following command will get the configurator for the initialized item and assign it a variable of your choice.

const configurator = window.player.getConfigurator()

To get the dataset for the attributes, we simply run:

configurator.getDisplayAttributes()

This function will return all the attributes, which includes both the options for the attribute and the selected value if any.

Finally when the user makes their selection, we pass that back on to the configurator as an object, where each key matches an Attribute and the value contains the users selection:

configurator.setConfiguration({"Attribute Name": value}})

It is worth noting that while most Attribute types (i.e. String, Color, Number) simply require us to pass the value to the setConfiguration function as demonstrated above, this is not true for Part Reference or Asset type Attributes. Those require the value itself to be an object containing the assetId of the item selected:

configurator.setConfiguration({ "Attribute Name": { assetId: "60a8a037-1438-4297-86da-24fb3a6c3b7b" }})

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();

Attribute Types

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

Primitive Values

configurator.setConfiguration({ Color: "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: { assetId: "26e0c72c-77a2-4fae-a81d-c995e32187f2" },
});

Setting Values

Let's begin with an example that takes values from an external form and sets the player's configuration.

<div>
  <label>Color:</label>
  <select name="Color" onchange="setConfig(event)">
    <option value="Blue">Blue</option>
    <option value="Black">Black</option>
    <option value="Green">Green</option>
    <option value="Grey">Grey</option>
    <option value="Red">Red</option>
  </select>

  <label>Wheels:</label>
  <select name="Wheels" onchange="setConfig(event)">
    <option value="26e0c72c-77a2-4fae-a81d-c995e32187f2"> Cool Option 1 </option>
    <option value="a3819592-3f98-4d32-bedd-2c0205d3ba5b">Awesome Option 2</option>
  </select>
</div>

<script>
  function setConfig(ev) {
    const attrName = ev.target.name;
    const value = ev.target.value;
    window.configurator?.setConfiguration({ [attrName]: value });
  }

  async function initPlayer() {
    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();
  }

  initPlayer();
</script>