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

The configurator API integration of a configuration revolves around matching configuration/part UUIDs with Variant UUIDs.

Collect part/variant UUIDs

You can find these UUIDs by listening to the sayduck.configurator.selectedConfigurationUpdated event. It gets emitted on load start as mentioned above, and on every subsequent selection update.

The code below can be pasted to the browser console.

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.

Custom event

'sayduck.configurator.actions.updateSelectedConfiguration'

Change variant in part with no groups

"[part1-uuid]": "[variant1-uuid]"

window.dispatchEvent(
   	new CustomEvent(
     	'sayduck.configurator.actions.updateSelectedConfiguration', {
	    	  detail: {
                   // part -> variant
                   "[part-uuid]": "[variant-uuid]"
     		}
   		}
     )
   );

Change variant in part with groups

"[part1-uuid]": "[group1-uuid]",
"[group1-uuid]": "[variant1-uuid]"

window.dispatchEvent(
   	new CustomEvent(
     	'sayduck.configurator.actions.updateSelectedConfiguration', {
	    	  detail: {
 	    	    // part -> group
   	    	    "[part-uuid]": "[group-uuid]",
                   // group -> variant
   	    	    "[group-uuid]": "[variant-uuid]"
     		  }
   		}
   )
);

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

window.dispatchEvent(
   	new CustomEvent(
     	'sayduck.configurator.actions.updateSelectedConfiguration', {
	    	  detail: {
 	    	    // part -> null
   	    	    "[part-uuid]": null
     		  }
   		}
   )
);

Initial configuration

The initial configuration can be used to load a specific configuration on load.

<div class="sayduck-3d-viewer-container" style="min-height:450px;min-width:300px;width:100%;height:100%;"
    data-product-uuid="[product-uuid]" data-viewer-options='{
   "configurations":{
      "initial":{
         "[part1-uuid]":"[variant1-uuid]",
         "[part2-uuid]":"[group1-uuid]",
         "[group1-uuid]":"[variant2-uuid]"
      }
   }
}'></div><script defer type="text/javascript" src="https://viewer.sayduck.com"></script>

Example Configurator integration

This basic example loads the configurator with buttons to change variants.

Example integration: https://jsfiddle.net/bchr2taj/2/

<div class="sayduck-3d-viewer-container" style="min-height:450px;min-width:300px;width:100%;height:100%;"
    data-product-uuid="9e903370-720a-013a-5d47-02cc273f194a" data-viewer-options='{"appearance":{"background":"gray","hide-picker":true,"enable-qr-code":true}}'>
  </div><script defer type="text/javascript" src="https://viewer.sayduck.com"></script>

<button id="whiteBtn">White</button>
<button id="redBtn">Red</button>

<script>
document.getElementById("whiteBtn").onclick = function() {
    window.dispatchEvent(
   	new CustomEvent(
     	'sayduck.configurator.actions.updateSelectedConfiguration', {
	    	  detail: {
                   // part -> variant
                   "9eba1ac0-720a-013a-20e1-02cc273f194a": "9eabdad0-720a-013a-c55b-02cc273f194a"
     		}
   		}
     )
   );
}

document.getElementById("redBtn").onclick = function() {
    window.dispatchEvent(
   	new CustomEvent(
     	'sayduck.configurator.actions.updateSelectedConfiguration', {
	    	  detail: {
                   // part -> variant
                   "9eba1ac0-720a-013a-20e1-02cc273f194a": "9eb05500-720a-013a-563a-02cc273f194a"
     		}
   		}
     )
   );
}
</script>

Updated on: 07/03/2023