1 Embedding a product in a 3D Viewer
1.1 Basic embed code
1.2 Additional options
1.2.1 Size
1.2.2 Background
1.2.3 Default variant
1.2.4 Initial configuration (Configurator mode)
1.2.5 Fullscreen button
1.2.6 Light switch button
1.2.7 Dimensions
1.2.7.1 Hiding the dimensions button
1.2.7.2 Showing dimensions on page load
1.2.8 Variant picker
1.2.8.1 Hiding the picker
1.2.8.2 Show open picker on page load
1.2.8.3 Picker label (Configurator mode)
1.2.9 Photo studio button
1.2.10 Hiding the preview image
1.2.11 Hiding the hand hint
1.2.12 Loading
1.2.12.1 Variant loading
1.2.12.2 Manual loading
1.2.12.3 Load on demand (Configurator mode)
1.2.13 User interactions
1.2.13.1 Disable zooming
1.2.13.2 Disable rotating
1.2.13.3 Disable panning
1.2.13.4 Autorotate
1.2.14 hide-variants (legacy)
2 Interact with the 3D Viewer
2.1 Messages sent by the viewer
2.1.1 Loading
2.1.1.1 Loaded
2.1.1.2 Ready
2.1.1.3 Complete
2.1.2 Messages sent in configurator mode (Pro version)
2.1.2.1 Selection
2.1.3 Analytics (Pro version)
2.1.3.1 Viewer hovered
2.1.3.2 Initial interaction
2.1.3.3 Interaction session
2.1.3.4 Rotate
2.1.3.5 Zoom
2.1.3.6 Pan
2.1.3.7 Variants
2.1.4 Errors
2.1.4.1 Error 406
2.1.4.2 Error 404
2.1.4.3 Error 400
2.2 Messages listened to by the viewer
2.2.1 Calling the API
2.2.2 Public messages
2.2.2.1 Force resize the 3D Scene (iOS workaround - 04.2018)
2.2.3 Actions (Pro version)
2.2.3.1 Taking a photo of the product
2.2.4 Modelling messages (Pro version)
2.2.4.1 Getting all the meshes and materials IDs
2.2.5 Updating a material [Beta feature]
2.2.6 Viewer messages (Pro version)
2.2.6.1 Available actions
2.2.6.1.1 Get all available IDs
2.2.6.1.2 Select variant
2.2.7 Configurator messages (Pro version)
2.2.7.1 Parts, Shapes and Materials
2.2.7.2 Available actions
2.2.7.2.1 Get all available IDs
2.2.7.2.2 Select Shape
2.2.7.2.3 Select Material

1. Embedding a product in a 3D Viewer

1.1 Basic embed code

You can embed Sayduck's 3D Viewer in your site in a matter of seconds. All you need to do is copy the iframe code available in any 3D Viewer on https://catalog.sayduck.com, and paste it on your own site.

<iframe name="sayduck3dViewer" style="min-height:450px;min-width:300px;width:100%;height:100%;" src="https://sayduck.com/3d/Hzbq" frameborder="0"></iframe>



1.2 Additional options

There are a few options available when embedding the 3D Viewer in your website. The main options are visible via the Embed options button, in the Share menu inside the viewer itself (only on sayduck.com). They are then passed in your iframe as GET parameters in the src attribute.

1.2.1 Size

The viewer is fully responsive and mobile-compatible, so you can set the size best suited for your website. Of course, you can also define the iframe's size through CSS – for example to be able to manage media queries – and fit the viewer in your responsive layouts.

By default, the inline style attributes are:

min-height: 450px
min-width: 300px
width: 100%
height: 100%

1.2.2 Background

Parameter background-color
Accepted values studio,white,transparent
Default value studio
Example src="https://sayduck.com/3d/Hzbq?background-color=white"

By default, the 3D Viewer will display products in a "Studio" environment. However, if this does not fit your website's styling, there is the possibility to have a more neutral white background. Otherwise, if you want to have full control on the background (for example overlaying the rendered 3D on a picture or your own website's branding), you can use the transparent option which will make the 3D Viewer's background completely transparent. In this situation, you can overlay the 3D Viewer's iframe on any other HTML element with the background or content of your choice.



1.2.3 Default variant

Parameter starting-variant
Accepted values [variant-id],[variant-name]
Default value [first-variant-id]
Example src="https://sayduck.com/3d/Hzbq?starting-variant=05fabd2e-7d6a-4df8-b8b3-b394ba6539ad"

You can select which variant should the 3D Viewer load first. This enables you to match the default variant with the version of the product on your own webpage. You can do so either by passing the variant's id (that you can get through the Share menu on a 3D Viewer) or its name (that you can also find in the Share menu or in each variant's tooltip in the 3D Viewer's variant picker). However, please note that while variant ids are guaranteed not to change, name's might occasionally do so, and in case your requested variant's name does not exist, the viewer will default to the first variant.



1.2.4 Initial configuration (Configurator mode)

Parameter initial-configuration
Accepted values [partId]:[shapeId]:[materialId],[otherPartId]:[otherShapeId]:[otherMaterialId],...
Default value For each part, loads first available shape with its first available material
Example src="https://sayduck.com/3d/sNvE?initial-configuration=oG4Mp0pq2EeCzMz9HQoCAZ0N0MA:5VgPWwFXds0CAAYK1Cafo6htZmU:vcuehz77p7"

In configurator mode, the first configuration loaded by default is the first choice of shape and material for each of the available parts. Specifically, this means that optional part will be disabled by default on load.

You can specify the exact configuration you want shown first to the user by using the initial-configuration parameter and the unique IDs of the parts, shapes and materials of the product (see details on how to get the IDs for a product in the Configurator messages section of this documentation) . When receiving a comma-separated list of IDs to that parameter - where each list element of the form [partId]:[shapeId]: [materialId] - the configurator will (load and) display first the specific shape with the specific material for the specific part matching the passed-in IDs.

In case you omit the shapeId or materialId - by passing a value of the form [partId]::[materialId] or [partId]: [shapeId]: - the default is to take the first available option for the omitted value. This is especially useful if there's only one option available, and it is thus superfluous to specify which should be displayed first.

In combination with the hide-picker parameter, this enables you to display the single given configuration of your choice in the configurator.

NB: when using a custom initial configuration, the preview image will automatically be hidden on load (similar to using the hide-preview parameter), to prevent mismatch between preview and initial 3D shown.

1.2.5 Full screen button

Parameter hide-full-screen-button
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-full-screen-button=1"

You can hide the full-screen button from the viewer to make the interface less cluttered.



By default, the full-screen button brings the user to a page on sayduck.com with only the product's name, brand and the available variant - on top of the product in 3D - without any distinctive branding.



1.2.6 Light switch button

Parameter hide-light-switch
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-light-switch=1"

On lamp products, the 3D Viewer supports ON and OFF mode, which is toggled by the light-switch button.



You can hide the light-switch button from the viewer to make the interface less cluttered.



1.2.7 Dimensions

The 3D Viewer supports product dimensions. When the dimensions button is clicked, the product dimensions will be displayed in the 3D Viewer, as can be seen below. Dimension values can be managed on Sayduck's delivery system, if you are the owner of the product or brand.



1.2.7.1 Hiding the dimensions button

Parameter hide-dimensions
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-dimensions=1"

You can hide the dimensions button from the 3D Viewer if you wish. A checkbox toggle can be found in the Embed options of 3D Viewers on sayduck.com.



1.2.7.2 Showing dimensions on page load

Parameter show-dimensions-on-load
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?show-dimensions-on-load=1"

You can also decide to have the dimensions showing by default in the initial loaded scene by using the parameter show-dimensions-on-load. Note that if you both hide the dimensions button and show dimensions on page load, the user will not be able to hide the dimensions and they will always appear on top of the visualized product.

1.2.8 Variant picker

1.2.8.1 Hiding the picker

Parameter hide-picker
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-picker=1"

You can hide the variant picker (or configuration picker in configurator mode). This will enable you to use your own HTML element for picking variants/configurations through the API (Pro Version only).

Note that if what you are trying to achieve is to display only one variant/configuration (in case you have one product page per variant on your site, and only want to show the relevant version in 3D), you should rather use the GET parameter load-only-initial (possibly in combination of a selection of a default variant through the GET parameter starting-variant), because it will make the viewer lighter by downloading only the 3D assets for that specific variant.



1.2.8.2 Show open picker on page load

Parameter open-picker-on-load
Accepted values 0,1
Default value Variant mode: 1 | Configurator mode: 0
Example src="https://sayduck.com/3d/Hzbq?open-picker-on-load=1"

By default, in configurator mode, the configuration picker will be closed on page load (since it is fairly big, it might otherwise obstruct the product), and in variant mode, it will be open (until the user makes a first variant selection).

You can change this behavior by manually setting the open-picker-on-load to the value matching your need.

1.2.8.3 Picker label (Configurator mode)

Parameter configurator-label
Accepted values Any URI Encoded string
Default value Configure
Example src="https://sayduck.com/3d/Hzbq?configurator-label=A%20%22complicated%22%20text%20%26%20symbols"

You can customize the text displayed on the Configurator picker, which by default is "Configure". Just pass in your desired label, URI-encoded (in JavaScript, you can use the built-in encodeURIComponent function) to the configurator-label parameter. The example above represents the label: A "complicated" text & symbols.



1.2.9 Photo studio button

Parameter hide-photo-studio
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-photo-studio=1"

The 3D Viewer provides a Photo Studio feature, which enables the user to take and download pictures of the product or any of its details from any angle. A few typical view angles are also available as shortcuts.



If you do not want your user to be able to download product shots from the Photo Studio, you can hide it from the 3D Viewer if you wish. A checkbox toggle can be found in the Embed options of 3D Viewers on sayduck.com.



NB: Taking a photo sometimes crashes on devices with lower memory. As such, the Photo Studio the feature is hidden by default on mobile devices, although you can manually choose to display it anyways.

1.2.10 Hiding the preview image

Parameter hide-preview
Accepted values 0,1
Default value 0

Example src="https://sayduck.com/3d/Hzbq?hide-preview=1"

If you do not want the viewer to load a preview image (jpg for background=white, png for other background options), you can set hide-preview=1.

1.2.11 Hiding the hand hint

Parameter hide-hand-hint
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-hand-hint=1"

After the product has finished loading, a moving hand hint will attract the user's attention to the fact that they can interact with the 3D Viewer. In case you do not want that hint to be displayed, you can simply use the hide-hand-hint=1 parameter. In that case, the product will by default autorotate (which you can also disable by explicitly setting autorotate=0).



1.2.12 Loading

1.2.12.1 Variant loading

Parameter load-only-initial
Accepted values 0,1
Default value 0

Example src="https://sayduck.com/3d/Hzbq?load-only-initial=1"

You can decide to load only the initial variant (or configuration in configurator mode) by using this parameter, which makes the 3D Viewer lighter for the user.

Note that this will automatically hide the variant/configuration picker (as if you also set the GET parameter hide-picker).

1.2.12.2 Manual loading

Parameter manual-load
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?manual-load=1"

If you do not want the 3D Viewer to automatically start on page load, you can set this parameter to 1, which will require the user to explicitly click on the 3D Viewer for it to initialize. Before then, the viewer will show an image preview, a rotating cube and a message inviting the user to interact to benefit from the 3D capabilities.



1.2.12.3 Load on demand (Configurator mode)

Parameter load-on-demand
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?load-on-demand=1"

You can decide to use the load-on-demand parameter, which makes the Configurator load only the initial configuration in a first step, and then download the data on demand only when the user selects a new configuration. That makes configurators a lot faster initially and spares the user some unnecessary data download.

The downside is that there might be a short delay between when the user selects a new configuration and when it actually appears on the render, delay during which a default loading animation is displayed.

1.2.13 User interactions

1.2.13.1 Disable zooming

Parameter disable-zoom
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?disable-zoom=1"

You can remove the ability for a user to zoom on the product by using the parameter disable-zoom=1.

1.2.13.2 Disable rotating

Parameter disable-rotate
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?disable-rotate=1"

You can remove the ability for a user to rotate the product by using the parameter disable-rotate=1.

1.2.13.3 Disable panning

Parameter disable-pan
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?disable-pan=1"

You can remove the ability for a user to move the product around by using the parameter disable-pan=1.

1.2.13.4 Autorotate

Parameter autorotate
Accepted values any float
Default value 0
Example src="https://sayduck.com/3d/Hzbq?autorotate=-0.7"

You can enable autorotate at your desired speed by using the parameter autorotate with any value (positive or negative) that you want. Positive values will rotate counter-clockwise. You can use values with decimal points.

The product will then rotate at the desired speed until the user interacts with the viewer. When the user stops interacting, the product will start autorotating again after a small delay.

1.2.13.5 hide-variants (legacy)

Parameter hide-variants
Accepted values 0,1
Default value 0
Example src="https://sayduck.com/3d/Hzbq?hide-variants=1"

This will behave as hide-picker=1&load-only-initial=1.

2 Interact with the 3D Viewer

To communicate with the parent page on which it is embedded, Sayduck's 3D Viewer uses the postMessage API to send and receive messages. In the following sections, we detail the available messages, and their data format. As detailed in the postMessage API documentation, you can setup event listeners to catch the messages and react appropriately.

Example

function receiveMessage(event) {
var origin = event.origin || event.originalEvent.origin; // For Chrome, the origin property is in the event.originalEvent object.
if (origin !== "https://sayduck.com") // if you embedded the 3D Viewer with a '//sayduck.com' (and your site is using plain http)
// or 'http://sayduck.com' you will need to use: 'origin !== "http://sayduck.com"'
// this is NOT recommended
return;
// do something with event.data || event.originalEvent.data
};
window.addEventListener("message", receiveMessage, false);


2.1 Messages sent by the viewer

The viewer posts messages on a variety of specific occasions. We detail here the content of event.data, as defined by the postMessage API.

2.1.1 Loading

2.1.1.1 Loaded

// event.data
{
"event": "loaded",
"code": 102,
"message": "Viewer has finished loading and will start loading content"
}


This is sent when the javascript file holding Sayduck's 3D Viewer's code has been downloaded and parsed. This means the 3D Viewer will now proceed to download the product's data.

2.1.1.2 Ready

// event.data
{
"event": "ready",
"code": 200,
"message": "3D is ready to be displayed"
}


This is sent when all the 3D data for the initial variant/configuration has been downloaded successfully and it is now ready to be shown. You might want to decide to hide the 3D Viewer at first, and display when this message is posted to prevent users from seeing any kind of loading screen.

2.1.1.3 Complete

// event.data
{
"event": "complete",
"code": 104,
"message": "All 3D content has loaded"
}


This is sent when all the 3D Data (meaning other variants/configurations than the initial one) has been downloaded.

2.1.2 Messages sent in configurator mode (Pro version)

2.1.2.1 Selection

// event.data
{
"event": "selection",
"code": 600,
"message": "A configuration has been selected",
"data": {
"type": "[initial|shape|material]",
"id": "[shapeId|materialId]",
"name": "[shapeName|materialName]", // for debugging purposes
"for": "[partId|shapeId]",
"forName": [partName|shapeName]", // for debugging purposes
"configuration": {
"[partId]": {
"partName": "[partName]", // for debugging purposes
"shapeId": "[shapeId]",
"shapeName": "[shapeName]", // for debugging purposes
"materialId": "[materialId]", // "[materialId]" might be 'undefined' if [shapeId] == "disabled"
"materialName": "[materialName]", // for debugging purposes
},
...
}
}
}


In configurator mode, the Pro version of the 3D Viewer will send an event when a new configuration is selected. Listening to this events lets you update information on your page based on the configuration selected by the user (for example, update the displayed price to match the current configuration).

This event presents the same basic attributes as all other events, like event (human-readable name of the event), code and message (human-readable description of the event) It also has a data attribute containing information regarding the configuration selection that was just made.

The data attribute has itself several attributes:

type - which indicates what triggered the new selection. Can be either "initial" (triggered along with the ready event at the end of data downloading), "shape" (if a shape selection was at the origin of this event), or "material" (if a material selection was at the origin of this event)

id - which gives the Sayduck ID of the element that triggered the event depending on the event type. Can be either undefined (for the initial event type), the matching "[shapeId]" (for the shape event type), and the matching "[materialId]" (for the material event type)

for - which gives the Sayduck ID of the element to which the triggering element will be applied. Can be either undefined (for the initial event type), the "[partId]" (for the shape event type), and the "[shapeId]" (for the material event type).

configuration - which gives a complete description of the active configuration after the selection. In most use case, this is the only parameter you need to update information on your website to match the new configuration. It is a javascript object which has a "[partId]" key for each part of the product and each matching value is an object of the form {"shapeId": "[shapeId]", "materialId": "[materialId]"}.

2.1.3 Analytics (Pro version)

2.1.3.1 Viewer hovered

// event.data
{
"event": "hovered",
"code": 501,
"message": "The user has hovered on the viewer"
}


This message is posted when the user hovers (puts the mouse over without necessarily interacting, or touched on mobile) for the first time. Given iframe limitations, this is our best estimate to know if the user has seen the viewer at all (for example on pages when the viewer is placed lower on the page and scrolling is necessary to even see it).

2.1.3.2 Initial interaction

// event.data
{
"event": "interaction",
"code": 502,
"message": "The user has interacted with the viewer"
}


This message is posted after the user has interacted directly with the viewer (zooming and/or rotations) continuously without breaks longer than 800ms. It represents an "interaction session" because it is sent again only if the user stops interacting for over 800ms.

2.1.3.3 Rotate

// event.data
{
"event": "rotate",
"code": 503,
"message": "The user has rotated"
}


This message is posted everytime the user rotates.

2.1.3.4 Zoom

// event.data
{
"event": "zoom",
"code": 504,
"message": "The user has zoomed"
}


This message is posted everytime the user zooms.

2.1.3.5 Pan

// event.data
{
"event": "pan",
"code": 505,
"message": "The user has panned"
}


This message is posted everytime the user pans.

2.1.3.6 Variants

// event.data
{
"event": "variant",
"code": 506,
"message": "The user has switched variant",
"data": {
"id": "[variantId]",
"name": "[variantName]", // for debugging purposes
}
}


This message is posted everytime the user selects a new variant in the variant picker.

2.1.4 Errors

2.1.4.1 Error 406

// event.data
{
"event": "error",
"code": 406,
"message": "WebGL is not supported by client"
}


A message is also posted if the viewer fails to start on the user's computer. Older devices with underperforming hardware, outdated graphics card or browsers might not have the ability to render products in 3D. In that case, they will be shown an error, and the 3D Viewer will first post you message to let you act on it if you wish.



2.1.4.1 Error 404

// event.data
{
"event": "error",
"code": 404,
"message": "This product is not available in 3D"
}


In very rare occasion, a product might be temporarily unavailable. In this case, the 3D Viewer will realize that it cannot download the 3D data from Sayduck's server, and will post the error 404. The Viewer will then display an error screen by default. You might want to listen for errors in order to hide the viewer (or not display it in the first place) and prevent the user from seeing the error screen.



2.1.4.2 Error 400

// event.data
{
"event": "error",
"code": 400,
"message": "An unknown error has occured"
}


Finally, an error message is also posted if any other error occured that prevented the viewer from loading properly. This is a fail-safe message that should never be posted. A generic error message will be shown to the end user.

2.2 Messages listened to by the viewer

2.2.1 Calling the API

The API works using the same postMessage API as for sending out messages. In that situation, you need to send messages with relevant actions for the configurator to perform. First, you need to get a reference to the Sayduck Configurator iframe. In order to do so, first check that the iframe tag you embedded on your page has its name attribute set to sayduck3dViewer, as shown in the example embed code at the top of this documentation.

Getting a reference is then just a matter of calling:

var sayduckIframe = window.frames.sayduck3dViewer

From there on, you can send messages to the Configurator. For example, you can change the material of the Fabric by calling:

sayduckIframe.postMessage({action:"configurator.select-material", shapeId:"BCtVusSli_CeggkjXm0fJR4zGiE", materialId:"amdx4fk5io"}, 'https://sayduck.com')

Typically, you would trigger this action when the user changes the selected fabric color from a dropdown (or similar selection mechanism) on your site.

API calls will return a message through the postMessage API, with the code parameter either 200 (OK) if the action call was legally formed, or 400 (bad request) if a parameter was missing. For example:

// event.data
{
"event": "configurator.select-material",
"code": 200,
"message": "OK"
}

or

// event.data
{
"event": "configurator.select-material",
"code": 400,
"message": "error: shape ID or material ID is missing"
}


2.2.2 Public messages

Any site embedding the viewer can send the following messages to the Viewer to perform dedicated actions.

2.2.2.1 Force resize the 3D Scene (iOS workaround - 04.2018)

On iOS, the iframe implementation is very buggy, and one relevant problem is that the window.resize event is not fired within an iframe. This is problematic in the case where you would like to hide the 3D Viewer embed from your page until a variant/configuration is ready to be shown (by listening to the 3D Viewer's ready event), and then only display the embed with a visible 3D content. On iOS, this will most likely result in an empty 3D Scene, and you will need to manually tell to the 3D Viewer that you changed the size (or visibility) of the iframe embed. You can do it by sending the following message:

var apiData = {
"action": "viewer.resized"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


This will result in the standard success answer and let the viewer know to resize its 3D Scene.

Typically, you would send this message right after you have updated the iframe embed within your ready event's listener.

2.2.3 Actions (Pro version)

2.2.3.1 Taking a photo of the product

You can request a photo of the rendering by using the actions.take-photo action.

var apiData = {
"action": "actions.take-photo",
"format": "image/jpeg", // Optional. Defaults to "image/png"
"noCrop": true, // Optional. Keeps the whitespace around the product (for example if it is zoomed out).
// Defaults to false
"keepPosition": true // Optional. Does not reset the product to its initial position.
// Might result in a partial image (for example if the product is zoomed in).
// Defaults to false
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


The 3D Viewer will then answer with a dataUrl which holds the data for the captured image.

// event.data
{
"event": "actions.take-photo",
"code": 200,
"message": "OK",
"data": {
"dataUrl": "data:image/jpeg;base64,/9j/4AAQSk..."
}
}


2.2.4 Modelling messages (Pro version)

2.2.4.1 Getting all the meshes and materials IDs

To be able to update a given material or mesh in the 3D Viewer, you first need to get its ID to be able to pass it to the viewer in the update call. This is achieved through the modelling.get-all-ids action.

var apiData = {
"action": "modelling.get-all-ids"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


The 3D Viewer will then answer with a list of all existing mesh IDs and their names, and a list of all material IDs and their names.

// event.data
{
"event": "modelling.get-all-ids",
"code": 200,
"message": "OK",
"data": {
"meshes": {
"[mesh1Id]": {
"id": "[mesh1Id]",
"name": "[mesh1Name]"
},
...
},
"materials": {
"[material1Id]": {
"id": "[material1Id]",
"name": "[material1Name]"
},
...
}
}
}


2.2.5 Updating a material [Beta feature]

You can update the materials displayed in the viewer directly through the API. Currently, only updating the albedo map is supported. To achieve this, you need to use the modelling.update-material action.

var apiData = {
"action": "modelling.update-material",
"materialId": "[materialId]",
"field": "albedo-map",
"newValue": "[textureAbsoluteUrl]"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


The 3D Viewer will then update the updated field with the new value, and reflect the changes as soon as possible.

Depending on the field update, an asynchronous update might be required (for example to download the new texture file). In that case, the viewer will first immediately return a message to let you know that the request was successful.

// event.data
{
"event": "modelling.update-material",
"code": 202,
"message": "Updating field "[field]" with value "[newValue]" for material "[materialId]"
}


Once the update is done, the viewer returns with a standard success message.

// event.data
{
"event": "modelling.update-material",
"code": 200,
"message": "Updated field "[field]" with value "[newValue]" for material "[materialId]"
}


2.2.6 Viewer messages (Pro version)

The 3D Viewer listens to messages you post to it, for example to select a new active variant. This enables you to change the variant displayed in 3D using elements on your own page (dropdown, swatch images...). Combined with hiding the variant picker, this would enable you to get a completely integrated look and feel of the 3D Viewer on your own pages.

2.2.6.1 Available actions

Get all available IDs
The API is based on unique IDs. Each variant has their own unique ID that is used in API calls and events. You can get an object describing all the available IDs by calling the viewer.get-all-ids action.

var apiData = {
"action": "viewer.get-all-ids"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


The 3D Viewer will then return an object with the following data, expliciting all existing variant IDs:

// event.data
{
"event": "viewer.get-all-ids",
"code": 200,
"message": "OK",
"data": {
"[variantId]": {
"id": "[variantId]",
"name": "[variantName]"
},
...
}
}


Select variant
You can select which variant to show by calling the viewer.select-variant action:

var apiData = {
"action": "viewer.select-variant",
"variantId": "[variantId]"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


2.2.7 Configurator messages (Pro version)

In configurator mode, the 3D Viewer listens to messages you post to it, for example to update the configuration it displays. This enables you to change the configuration displayed in 3D using elements on your own page (dropdown, swatch images...). Combined with hiding the configuration drawer, this would enable you to get a completely integrated look and feel of the configurator on your own pages.



2.2.7.1 Parts, Shapes and Materials

The configurator abstracts products into parts, shapes and materials. In the above example, the chair has 3 parts:

Fabric
Base
Armrests

Each part might have one or more shapes. In the above example, the Fabric part only has one shape (and thus the shape dropdown is invisible for that part), while the Base has 2 shapes, and the Armrests 3.



Finally, each shape has a range of available materials - except of course disabled shapes. On the example, the active material for the Fabric part is Light gray, the active material for the Z shape of the Base is Chrome, and the Armrests are disabled.

For more information, you can read the Configurator section of the Product Editor documentation.

Each part, shape and material come with a unique ID that you can use within the API to perform actions.

Please note that the API does not check if the IDs you are passing in are matching existing Sayduck IDs. If a call uses a non-existing ID, it will have no effect on the displayed configuration, and you will receive a successful answer message from the API. However, the configurator drawer - if visible - will show that the dropdown you tried to change to a non-existing shape or material does not have a selected element anymore.

2.2.7.2 Available actions

2.2.7.2.1 Get all available IDs
The API is based on unique IDs. Each part, each shape and each material has their own unique ID that is used in API calls and events. You can get an object describing all the available IDs by calling the configurator.get-all-ids action.

var apiData = {
"action": "configurator.get-all-ids"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


The configurator will then return an object with the following data, expliciting all existing IDs for parts, shapes and materials, and their hierarchy:

// event.data
{
"event": "configurator.get-all-ids",
"code": 200,
"message": "OK",
"data": {
"[partId]": {
"partName": "[partName]", // for debugging purposes
"shapes": {
"[shapeId]": {
"shapeName": "[shapeName]", // for debugging purposes
"disabled": [true|false],
"active": [true|false],
"materials": {
"[materialId]": {
"materialName": "[materialName]", // for debugging purposes
"disabled": [true|false],
"active": [true|false]
},
...
}
},
...
}
},
...
}
}


2.2.7.2.2 Select Shape
You can select which shape to show for a given part by calling the configurator.select-shape action:

var apiData = {
"action": "configurator.select-shape",
"partId": "[partId]",
"shapeId": "[shapeId]"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


To disable a given part, you can pass in disabled as the shapeId. If this part is actually optional, it will then be disabled.

var apiData = {
"action": "configurator.select-shape",
"partId": "[partId]",
"shapeId": "disabled"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');


2.2.7.2.3 Select Material
You can select which material to show for a given shape by calling the configurator.select-material action:

var apiData = {
"action": "configurator.select-material",
"shapeId": "[shapeId]",
"materialId": "[materialId]"
};
sayduckIframe.postMessage(apiData, 'https://sayduck.com');
Was this article helpful?
Cancel
Thank you!