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