Articles on: API

Configurator API

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: 08/04/2022

Was this article helpful?

Share your feedback

Cancel

Thank you!