The Configurations tab captures configuration information whenever a user hits the "Share" button within the player. While the share button in the player captures the present configuration, the Configurations API can be leveraged to capture the configuration based on any other event, such as adding to cart.
Configuration Details
Once the Share button is pressed, a record is created with the Configurations tab.
Each record retains the relevant configuration information.
In the Threekit platform, you can save your configuration for later retrieval. Here are examples of how to save a configuration as well as how to retrieve a save so the user sees a pre-set configuration load in the player by default, instead of starting from scratch.
Save a Configuration:
To be able to load a saved configuration we first need to create and save a configuration in the platform.
There are two ways to save a configuration:
1) click the Share Button on the player
2) call the configuration API
Share Button
First, you need to have this button available on the player so it can be clicked. Go to Settings -> Player Settings -> check the box in front of “Share Button” in the Embedded Player Elements section.
When this checkbox is turned on, you will be able to see the Share button on the player like this (highlighted in the screenshot below):
Clicking on the Share button will save the current configuration, and a link to the saved configuration will be generated - you can choose to copy the link or share via email or other social media. In the link there is a parameter “tkcsid=xyzabc123” appended to the end. This “tkcsid” is the shortId of this saved configuration. With this short id we will be able to retrieve this configuration. We will talk more about this in the Use a Saved Configuration section.
Saving a Configuration via an API call
What if you don’t want the share button to appear on the player? The Share button generates a link to load the Threekit player on the page of the user clicking the button. If the Player is behind a login, this generated share link will not work for users who can’t login to the system. In such a case, you may wish to save a configuration to store the ShortId and later access the configuration in a publicly-available Threekit Player.
This code snippet below defines a saveConfiguration() function that saves the current configuration to Threekit by doing an API call. You can then parse the response of the API call and get the id or shortId of the saved configuration. Then use that saved configuration Id as desired. See the Use a Saved Configuration section for an example snippet of code for a web page loading an existing configuration.
const configurationsUrl = `https://preview.threekit.com/api/configurations`;
const authToken = "ec4abcb8-1234-abcd-wxyz-d60cf8b99ab7";//replace it with your token
window.saveConfiguration = () => {
const configuration = window.configurator.getConfiguration();//window.configurator needs to be set in the code that embeds the threekit player.
const body = new FormData();
body.append("orgId", "<YOUR_ORG_ID>"); // replace second argument with your org id
body.append("productId", window.api.assetId);//window.api needs to be set in the code that embeds the threekit player.
body.append("productVersion", "1.0");
body.append("variant", JSON.stringify(configuration));
return fetch(`${configurationsUrl}?bearer_token=${authToken}`, {
method: "post",
body,
})//call the API to save the configuration
.then((res) => res.json())
.then((resJson) => console.log("saved configuration:", resJson))//This prints the response to the console so you can take a look at the response of this API call. When it’s a success you will be able to see the just saved configuration
.catch((e) => console.error(e));
};
Use a Saved Configuration:
Where to find the saved configurations
Now we have a configuration saved in the Threekit Platform, but where can we find it? Saved configurations are found under Orders -> Configurations. A list of all saved configurations are shown here.
Clicking into a saved configuration you will be able to see the details. The Configuration UUID or Configuration Short ID is the data we need to locate the configuration.
Load the player with a saved configuration
The example below shows HTML and JavaScript code that loads the player in the page with a previously saved configuration whose shortId is "PegDan0Zx".
Additionally, there is the function saveConfiguration() created as an example of saving a configuration. So when a user starts from the saved configuration and makes some tweaks then wants to save that new configuration, the saveConfiguration() can be called and a new id, as well as a new shortId will be generated. Some detailed explanations can be found in the comments within the code.
<meta name="viewport" content="width=device-width, initial-scale=1" />
<div id="player" style="width: 100%"></div>
<script src="https://preview.threekit.com/app/js/threekit-player.js"></script>
<script>
// Use public token enabled for domain (ex. localhost:8000) where this page will be loaded
const authToken = "ec4abcb8-1234-abcd-wxyz-d60cf8b99ab7";//the public token to the domain you’re using
const assetId = "58e2d62d-1234-abcd-wxyz-4bdf5384a771"; //id of your product's catalog item
//const stageId = "";
const configurationsUrl = `https://preview.threekit.com/api/configurations`;
const savedConfigId = "PegDan0Zx"; // The saved configuration’s id you want to load in the player, it can be the short id or the full id. Typically there are two ways to get the saved configuration id. It can either be hard-coded (like this example here) in the web page so the configuration is loaded as the default configuration of the player. Or there can be a mapping stored somewhere that you can query the stored data to find the shortId that’s mapped to the current user(or other filter criteria).
(async function () {
// load saved config
let initialConfiguration = null;
if (savedConfigId) {
const savedConfig = await fetch(
`${configurationsUrl}/${savedConfigId}?bearer_token=${authToken}`
)
.then((res) => res.json())
.catch((e) => console.error(e));
initialConfiguration = savedConfig.variant;
console.log("SavedConfig:", savedConfig);
}
window
.threekitPlayer({
el: document.getElementById("player"),
authToken: authToken,
assetId,
//stageId,
showConfigurator: true,
showShare: true,
initialConfiguration,
})
.then(async function (player) {
const configurator = await player.getConfigurator();
window.configurator = configurator;
window.api = player;
});
})();
window.saveConfiguration = () => {
const configuration = window.configurator.getConfiguration();//window.configurator was set in the code above that embeds the player, so we can call the getConfiguration() function from it.
const body = new FormData();
body.append("orgId", "1a345af5-1234-abcd-wxyz-5676a71a824b"); // replace second argument with your org id
body.append("productId", window.api.assetId);//window.api was set in the code above that embeds the player, so we can reference the assetId field.
body.append("productVersion", "1.0");
body.append("variant", JSON.stringify(configuration));
return fetch(`${configurationsUrl}?bearer_token=${authToken}`, {
method: "post",
body,
})
.then((res) => res.json())
.then((resJson) => console.log("saved configuration:", resJson))// Here the response is printed in console. In reality you’d want to parse the response and get the shortId and store it somewhere or generate a custom share link with it. If the configuration Id or shortId is not used at the time it is generated, it can be very difficult to find in the Threekit org.
.catch((e) => console.error(e));
};
</script>
