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 Custom theme color
1.2.4 Action menu
1.2.5 Dimensions
1.2.5.1 Hiding the dimensions button
1.2.5.2 Showing dimensions on page load
1.2.6 Photo studio
1.2.6.1 Hide icon
1.2.6.2 Request image
1.2.7 Embed button
1.2.8 Annotations
1.2.8.1 Hiding the annotations button
1.2.8.2 Showing annotations on page load
1.2.9 Variants
1.2.9.1 Initial variant
1.2.9.2 Hiding variant
1.2.9.3 Hiding the picker
1.2.9.4 Change displayed variant
1.2.9.5 Variant picker customization
1.2.10 Web AR
1.2.10.1 Desktop Web AR icon
1.2.10.2 Web AR button customization
1.2.11 Hiding the hand hint
1.2.12 Loading
1.2.12.1 Hide loading bar
1.2.12.2 click to load
1.2.12.2.1 click-to-load-background-repeat
1.2.12.2.2 click-to-load-background-size
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 Click to zoom
1.2.13.5 Two finger rotate
2.1 Dynamic 3D viewer
2.2 Dynamic USDZ viewer
3.1 Configurator

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 embed code from the embed & export tab, and paste it on your own site.

<div id="sayduck-3d-viewer-container" style="min-height:450px;min-width:300px;width:100%;height:100%;" data-product-uuid="f9340390-2087-0137-a0d4-6eec82cfb9d4"></div><script type="text/javascript" src="https://viewer.sayduck.com"></script>

1.2 Additional options

There are a few options available when embedding the 3D Viewer in your website. All of these options can be found in the customize embed code tab and easily applied to the embed code.

<div id="sayduck-3d-viewer-container" style="min-height:450px;min-width:300px;width:100%;height:100%;" data-product-uuid="f9340390-2087-0137-a0d4-6eec82cfb9d4"
data-viewer-options='{
"appearance": {
"background": "white",
"hide-photo-studio": true,
"hide-embed": true
},
"controls": {
"no-pan": true
}
}'></div><script type="text/javascript" src="https://viewer.sayduck.com"></script>




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 viewer 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%

Embed code

style="min-height:450px;min-width:300px;width:100%;height:100%;"

1.2.2 Background

By default, the 3D Viewer will display products in a "Gray" 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.

Parameter background
Accepted values white | light | gray | dark | transparent
Default value gray
Example "background": "transparent"

Embed code

data-viewer-options='{
"appearance": {
"background": "transparent"
}
}'




1.2.2.1 Background advanced

Parameter background-advanced
Accepted values hex color
Example "color": "#fcba03"

Embed code

"background-advanced": {
"color": "#fcba03"
}


Parameter background-advanced
Accepted values imageUrl
Example "image": "imageURL"

Embed code

"background-advanced": {
"image": "https://cdn.sayduck.io/a/shared_assets/files/000/774/646/ba36285b79a77429997f578e6f97ef37750bdcfffcbf77b2585d47985cd4a788-original.png"
}


Parameter background-advanced
Accepted values imageUrl
Example "cubeMap": [
"imageURL-positive-x.png",
"imageURL-negative-x.png",
"imageURL-positive-y.png",
"imageURL-negative-y.png",
"imageURL-positive-z.png",
"imageURL-negative-z.png"
]

Embed code

"background-advanced": {
"cubeMap": [
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/577/65a65493e7d33aec67096dd19d4bcaaaaff6f2440e71bcc31b40a8e4e2885935-original.png",
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/578/ad95de735cc02e253796827e3dd31802c072e467c7e8f02c076aedbeed0fe9f1-original.png",
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/591/caa0397e70f05c9e382ead3890d07bc6efedd84246e2e2abbfb467d8b74c4930-original.png",
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/576/465e42116fbe97162356448ab2e3e6adb199e89a9bf35f9228c87293c1515329-original.png",
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/575/b5c2abc6fba655240ecdd25575f6cadd9166196368c62cb00f3edba168b730e9-original.png",
"https://staging-cdn.sayduck.io/a/shared_assets/files/000/174/574/8aa6d13454df393c9d0ece6a7cc99b331e268d827ad7f310c546b700e6a78d43-original.png"
]
}


1.2.3 Custom theme color

The custom theme color will change the color of the loading bar and the spin effect. Choose a color that fits your brand theme.

Parameter theme-color
Accepted values 0-255 white | light | gray | dark | transparent
Example "theme-color":{"red":58,"green":217,"blue":205,"alpha":255}

Embed code

data-viewer-options='{
"appearance": {
"theme-color":{"red":58,"green":217,"blue":205,"alpha":255}
}
}'


1.2.4 Action menu

The action menu can be found from the top right corner of the 3D viewer. The active tools available in the menu are Dimensions, Photo studio, Embed and Annotations.

Parameter hide-action-menu
Accepted values true | false
Default value false
Example "hide-action-menu": true

Embed code

data-viewer-options='{
"appearance": {
"hide-action-menu": true
}
}'


1.2.5 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.

Edit Properties > Dimensions



1.2.5.1 Hiding the dimensions button

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.

Parameter hide-dimensions
Accepted values true | false
Default value false
Example "hide-dimensions": true

Embed code

data-viewer-options='{
"appearance": {
"hide-dimensions": true
}
}'




1.2.5.2 Showing dimensions on page load

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.

Parameter show-dimensions-on-load
Accepted values false | true
Default value false
Example "show-dimensions-on-load":true

Embed code

data-viewer-options='{
"appearance": {
"show-dimensions-on-load":true
}
}'


1.2.5.3 Dimensions API

Show dimension

window.dispatchEvent(new CustomEvent("sayduck.viewer.actions.showModelDataDimensions"))

Hide dimensions

window.dispatchEvent(new CustomEvent("sayduck.viewer.actions.hideModelDataDimensions"))

1.2.6 Photo studio

1.2.6.1 Hide Icon

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.

Parameter hide-photo-studio
Accepted values false | true
Default value false
Example "hide-photo-studio": true

Embed code

data-viewer-options='{
"appearance": {
"hide-photo-studio": true
}
}'




NB: Taking a photo sometimes crashes on devices with lower memory. As such, it is recommended to hide the Photo Studio feature on mobile devices.

1.2.6.2 Request photo

Available parameters

- format: "png"|"jpg" // Optional, defaults to "png"

- keepPosition: true|false // Optional. Does not reset the product to its initial position.
// Might result in a partial image (for example if the product is zoomed in).

- noCrop: true|false // Optional. Keeps the whitespace around the product (for example if it is zoomed out).

- verticalAngle: [-90,90] // Optional, defaults to 15.

- horizontalAngle:[-180,180] // Optional, defaults to -35.

- width: 2048 // Optional, defaults to 4096.

- height: 2048 // Optional, defaults to 4096.


Listen to photoTaken event

document.addEventListener('sayduck.viewer.photoTaken', function(event) { console.log(event.detail) });

Request a photo

window.dispatchEvent(new CustomEvent('sayduck.viewer.actions.takePhoto', { detail: { format: 'jpg', keepPosition: true, noCrop: true } }));

Example event.detail received:

{
dataUrl: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
verticalAngle: 15,
horizontalAngle: -35,
}


1.2.7 Embed

The viewer by default has an embed icon that displays the viewer embed code.

Parameter hide-embed
Accepted values false | true
Default value false
Example "hide-embed": true

Embed code

data-viewer-options='{
"appearance": {
"hide-embed": true
}
}'




1.2.8 Annotations

Annotations are interactable notes that have a camera position and a position on your product. They are used to highlight and give additional information the most important parts of your product. Check out annotations for more information.



1.2.8.1 Hide annotations button

The 3D Viewer supports product annotations. When the annotations button is clicked, the annotations will be displayed in the 3D Viewer and can be then interacted with.

Parameter hide-annotations
Accepted values true | false
Default value false
Example "hide-dimensions": true

Embed code

data-viewer-options='{
"appearance": {
"hide-dimensions": true
}
}'




1.2.8.2 Show the annotations on load

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

Parameter show-annotations-on-load
Accepted values false | true
Default value false
Example "show-annotations-on-load":true

Embed code

data-viewer-options='{
"appearance": {
"show-annotations-on-load":true
}
}'


1.2.9 Variants

1.2.9.1 Initial variant

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.

Parameter initial
Accepted values [variant-uuid]
Example "initial": "[variant-uuid]"

Embed code

data-viewer-options='{
"variants": {
"initial": "[variant_uuid]"
}
}'


1.2.9.2 Hiding variants

Select which variants you wish to include on your live 3D viewer. With this you do not have to delete and variants completely, but you can just hide them temporarily.

Embed code

Parameter include
Accepted values [variant-uuid]
Example "include": ["variant_uuid", "variant_uuid2", ...]

data-viewer-options='{
"variants": {
"include": ["variant_uuid", "variant_uuid2", ...]
}
}'


1.2.9.3 Hiding the picker

You can hide the variant picker. This will enable you to use your own HTML element for picking variants through the API.

Parameter hide-picker
Accepted values false | true
Default value false
Example "hide-picker": true

Embed code

data-viewer-options='{
"appearance": {
"hide-picker": true
}
}'




1.2.9.4 Change displayed variant

Change the displayed variant without reloading the viewer. May be used to create a new variant picker when used together with hide-picker.

window.dispatchEvent(
new CustomEvent("sayduck.viewer.actions.showModel", {
detail: {modelUuid: "variantUuid" }
})
);


Check out Custom Variant Picker for more information.

You can find variant UUID by selecting it on the product page.

1.2.9.5 Variant picker customization

Background color of the variant picker button.

Parameter pickerBackground
Accepted values 1-255
Default value rgba(255,255,255, 0.3)
Example "buttonBackground": "rgba(255,255,255, 0.3)"

Variant picker text color.

Parameter pickerTextColor
Accepted values color
Default value "black"
Example "pickerTextColor": "black"

Button border thickness and color.

Parameter border
Accepted values [px] [color]
Default value 1px solid black
Example "border": "1px solid black"

data-viewer-options='{
"appearance":{
"mobile-ui-settings": {
"pickerBackground": "rgba(255,255,255, 0.3)",
"pickerTextColor": "black",
"border": "1px solid black"
}
}
}'




1.2.10 Web AR

The 3D viewer provides the option to direct users from web to AR with one-click.

Parameter hide-web-ar
Accepted values false | true
Default value false
Example "hide-web-ar": false

Embed code

data-viewer-options='{
"appearance": {
"hide-web-ar": false
}
}




1.2.10.1 Desktop Web AR icon

Web AR icon opens QR code which opens the AR viewer when scanned on a mobile device.

Parameter enableQrCode
Accepted values false | true
Default value false
Example "enable-qr-code": false

data-viewer-options='{
"appearance": {
"enable-qr-code": true
}
}'




1.2.10.2 Web AR button customization

Displayed text in Web AR button.

Parameter arText
Accepted values "text"
Default value "Discover in AR"
Example "arText": "Discover in AR"

Background colour of the Web AR button.

Parameter buttonBackground
Accepted values 1-255
Default value rgba(255,255,255, 0.3)
Example "buttonBackground": "rgba(255,255,255, 0.3)"

Button text color.

Parameter buttonTextColor
Accepted values color
Default value black
Example "buttonTextColor": "black"

Button border thickness and color.

Parameter border
Accepted values [px] [color]
Default value 1px solid black
Example "border": "1px solid black"

data-viewer-options='{
"appearance":{
"mobile-ui-settings": {
"arText": "Discover in AR",
"buttonBackground": "rgba(255,255,255, 0.3)",
"buttonTextColor": "black",
"border": "1px solid black"
}
}
}'




1.2.10.3 Custom action button (iOS)

Parameter title | subtitle | callToActionLabel
Accepted values text
Example values "title": "Test title" | "subtitle": "Test subtitle" | "callToActionLabel": "Buy"

data-viewer-options='{
"appearance": {
"ios-ar-custom-action": {
"title": "Test title",
"subtitle": "Test subtitle",
"callToActionLabel": "Buy"
}
}
}'


1.2.10.3.1 Custom action event

document.addEventListener("sayduck.viewer.iosArCustomAction.clicked", (e) => console.log(e.detail), false);

1.2.11 Hiding the hand hint

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).

Parameter hide-hand-hint
Accepted values false | true
Default value false
Example "hide-hand-hint": true

Embed code

data-viewer-options='{
"appearance": {
"hide-hand-hint": true
}
}'




1.2.12 Loading

1.2.12.1 Hide loading bar

Parameter "hide-loading-bar": true
Accepted values false | true
Default value false
example "hide-loading-bar": true

Embed code

data-viewer-options='{
"appearance": {
"hide-loading-bar": true
}
}'


1.2.12.1 Load new product without reloading page

To load a new product without reloading the page, use this event. It updates the productUuid directly in the embed code. It is most commonly used in one page ecommerce themes.

Replace the productUuid with the that of your chosen product.

window.dispatchEvent(
new CustomEvent("sayduck.viewer.actions.update3dViewer", {
detail: {productUuid: "productUuid]"}
})
);


1.2.12.2 Click to load

The 3D viewer is only loaded after one clicks it.

Parameter "show-click-to-load":true
Accepted values false | true
Default value false
example "show-click-to-load":true

Embed code

data-viewer-options='{
"appearance": {
"show-click-to-load": true
}
}'




1.2.12.2.1 click-to-load-background-repeat

Parameter click-to-load-background-repeat
Accepted values no-repeat | repeat
Default value no-repeat
Example "click-to-load-background-repeat": "no-repeat"

data-viewer-options='{
"appearance": {
"click-to-load-background-repeat": "no-repeat"
}
}'


1.2.12.2.2 click-to-load-background-size

Parameter click-to-load-background-size
Accepted values contain | cover
Default value contain
Example "click-to-load-background-size": "contain"

data-viewer-options='{
"appearance": {
"click-to-load-background-size": "contain"
}
}'


1.2.13 User interactions

1.2.13.1 Disable zooming

You can remove the ability for a user to zoom by scrolling the mouse wheel (mobile: Pinch in/out with your fingers).

Parameter disable-zoom
Accepted values false | true
Default value false
Example "no-zoom": true

Embed code

data-viewer-options='{
"controls": {
"no-zoom": true
}
}'


1.2.13.2 Disable rotating

You can remove the ability for a user to rotate the product by clicking and holding the left mouse button (mobile: 1 finger drag).

Parameter disable-rotate
Accepted values 0,1
Default value 0
Example "no-rotate": true

Embed code

data-viewer-options='{
"controls": {
"no-rotate": true
}
}'


1.2.13.3 Disable panning

You can remove the ability for a user to move the product around by clicking and holding the right mouse button (mobile: 2-finger drag).

Parameter disable-pan
Accepted values 0,1
Default value 0
Example "no-pan": true

Embed code

data-viewer-options='{
"controls": {
"no-pan": true
}
}'


1.2.13.4 Click to zoom

Allow zooming without first clicking on the 3D Viewer. This option might interfere when the user is scrolling down the page.

Parameter no-click-to-zoom
Accepted values true | false
Default value false
Example "no-click-to-zoom": true

Embed code

data-viewer-options='{
"controls": {
"no-click-to-zoom": true
}
}'


1.2.13.5 Two finger rotate

Rotation on mobile will require two fingers to prevent interference when the user is swiping to scroll down the page.

Parameter two-finger-rotate
Accepted values true | false
Default value false
Example "two-finger-rotate": true

Embed code

data-viewer-options='{
"controls": {
"two-finger-rotate": true
}
}'


2.1 Dynamic 3D viewer

Dynamic 3D Viewer allows our users to update the Base Colour texture on an embedded 3D viewer directly with an javascript event. This can be used to create custom products like Mugs, Pillows or Paintings by letting your customers upload their own .jpg or .png texture to an template 3D product.

For more information Dynamic 3D Viewer.



Dynamic USDZ viewer

The dynamic AR is a completely different product of ours, called the Dynamic USDZ Viewer (with a similar but separate tier pricing than the Dynamic 3D Viewer), with a slightly different implementation.

For the dynamic USDZ viewer to work correctly, you should disable the web AR in the 3D Viewer, which does not support dynamically updated texture.

For more information Dynamic USDZ Viewer.

3.1 Configurator

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.

For more information Configurator API.
Was this article helpful?
Cancel
Thank you!