Configurator API

To communicate with Sayduck's 3D Configurator, you can use the JavaScript API, which is based upon plain JavaScript events.. In the following sections, we detail the available messages, and their data format. You can setup event listeners to catch the events and react appropriately.

Sayduck picker

The Sayduck picker is available for all our users. It will create an simple picker that you can customize and improve to fit your theme.

<div id="sayduck-3d-configurator-picker-container"></div>
<script defer src="https://configurator-picker.sayduck.com"></script>


If you do not wish to build your own picker, here is the picker from the Shareable preview. You will only need to replace the product-uuid with your products uuid found in the embed code.

<div class="sayduck-3d-viewer-wrap" style="position:relative;">
<div id="sayduck-3d-viewer-container" style="min-height:350px;min-width:300px;width:100%;height:100%;"
data-product-uuid="product-uuid" >
</div><script defer type="text/javascript" src="https://viewer.sayduck.com"></script>
<div id="sayduck-3d-configurator-picker-container" style="position: absolute; bottom: 0; max-width: calc(100% - 62px); background: rgba(0,0,0,0.2); border-top-right-radius: 10px; padding: 16px;"></div>
</div>
<script defer src="https://configurator-picker.sayduck.com"></script>


Custom picker

Listen to the Viewer

At load start, the configurator will output the following object with all the possible options and which are currently selected:

Part:
[part-uuid]:
label: "part"
optionsLabel: "part"
position: X
swatchColour: undefined
parent: null
optional: true | false
children: [variant-uuid] | [group-uuid]


Group:
[group-uuid]:
label: "group"
optionsLabel: "group"
position: X
swatchColour: undefined
parent: [part-uuid]
optional: false | true
children: [variant-uuid]
selected: [variant-uuid]


Variant
[variant-uuid]:
label: "variant"
optionsLabel: "variant"
position: X
swatchColour: {red: 1-255, green: 1-255, blue: 1-255, alpha: 1-255
parent: [part-uuid]
optional: false
children: [variant-uuid]
selected: [variant-uuid]


In general, you can grab this object by listening to the sayduck.configurator.selectedConfigurationUpdated event. It gets emitted on load start as mentioned above, and on every subsequent selection update.

document.addEventListener("sayduck.configurator.selectedConfigurationUpdated", (e) => console.log(e.detail), false);

Interact with the Viewer

To change configurations, you will need to assign two configuration uuids. If your part has groups, you will need to select the group as well as the variant.

Change part with no groups:
[part1-uuid]: [variant1-uuid]

Change part with groups:
[part2-uuid]: [group1-uuid],
[group1-uuid]: [variant2-uuid]


Example:

document.addEventListener('sayduck.viewer.gltf.loaded', () => {
window.dispatchEvent(
new CustomEvent(
'sayduck.configurator.actions.updateSelectedConfiguration', {
detail: {
// part1 -> variant1
[part1-uuid]: [variant1-uuid],
// part2 -> group1
[part2-uuid]: [group1-uuid],
// group -> variant
[group1-uuid]: [variant2-uuid]
}
}
)
);
}, false);


Optional part

Users can check their configuration parts as optional. This will enable an "Disabled" option to the configurator picker. With API you can disable and enable optional parts with the following uuids.

Disable part:
[part-uuid]: null

Enable part:
[part-uuid]: [group-configuration-uuid]

Tutorial Configurator

This basic example loads the embedded configurator, logs the JSON object with the configuration options to the console, and then changes the selected configuration once the initial one has loaded.

Example product: https://jsfiddle.net/yeb483am/6/

Here is also the embed code, which you can just paste on any webpage. This will load the demo configurator.

<div id="sayduck-3d-viewer-container" style="min-height:450px;min-width:300px;width:100%;height:100%;" data-product-uuid="3601c3e0-4c1a-0138-8644-723a24a959be" ></div><script defer type="text/javascript" src="https://viewer.sayduck.com"></script>

Here is an function that will display all your configuration uuids.

$(function() {
document.addEventListener("sayduck.configurator.selectedConfigurationUpdated", (e) => console.log(JSON.stringify(e.detail, null, 2)), false);
});




Finally, you can pretty easily request for a configuration update by dispatching the following event using values from the configuration object. For example, this event would change the selected seat colour, along with the legs material and adds the cushion mesh and material:

$(function() {
document.addEventListener("sayduck.configurator.selectedConfigurationUpdated", (e) => console.log(e.detail), false);

document.addEventListener('sayduck.viewer.gltf.loaded', () => {
window.dispatchEvent(
new CustomEvent(
'sayduck.configurator.actions.updateSelectedConfiguration', {
detail: {
// seat -> Red
'36052dd0-4c1a-0138-15d6-723a24a959be': '3c116c10-4c1b-0138-a591-723a24a959be',
// legs -> Back Stained Oak
'ee8a5e10-4c1a-0138-e2af-723a24a959be': '1984d970-4c1b-0138-7e7a-723a24a959be',
// cushion -> fabric
'42053190-4c1b-0138-b2d8-723a24a959be': '5d02e530-4c1b-0138-8526-723a24a959be',
// fabric -> grey
'5d02e530-4c1b-0138-8526-723a24a959be': '5f79b380-4c1b-0138-a5da-723a24a959be',
}
}
)
);
}, false);
});


Was this article helpful?
Cancel
Thank you!