Documentation
Discussions

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. 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.

❗️

Always use await with setConfiguration, as it is necessary to ensure the configuration is passed fully before performing any additional tasks.

await configurator.setConfiguration({attrName: attrValue})

Configuration Object

Here is an example of the type definition for the Configuration Object that can be passed to the setConfiguration method.

type AttributeValue =
  | string // if it's a String Attribute
  | number // if it's a Number Attribute
  | boolean // if it's a Boolean Attribute
  | { r: number, g: number, b: number } // if it's a Color Attribute
  | { // If it's a Part Reference or Asset Attribute
    // Exactly 1 of these 3 should be provided:
    assetId?: string;
    customId?: string;
    query?: { metadata: { [key: string]: any } };

    configuration?: Configuration // Optional, for nested configurations
}

type Configuration = {
  [attributeName: string]: 
    | AttributeValue // For single value Attributes
    | AttributeValue[] // for Array Attributes
}

Custom IDs

You can set a Threekit configuration using the Custom ID you have associated with a catalog item. This will work with part-reference attributes. 

await configurator.setConfiguration({attrName: {customId: yourCustomID}})

Metadata Queries

If you would like to be able to set a part-reference attribute type with data that is human readable or that aligns with client-data identifiers, you can use a metadata query. Ensure the key: value pair on your item exists and matches what you are using to setConfiguration.

Please be sure you do not have items with duplicate metadata or you may see unexpected results

await configurator.setConfiguration({
  Finish: { // The attribute you would like to set
    query: {
      metadata: {
        Finish: "Brass", // the metadata key:value pair that exists on the item
      },
    },
  },
});

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

await 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

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

Arrays

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