Getting Started
The Dimensions 3D Viewer can be integrated easily using the Dimensions Tag and a few lines of Javascript.
Be sure to add the scripts mentioned in the article linked above before proceeding with the instructions below.
You should have a container marked with the correct attributes that tell the Tag where to embed the Viewer within your page. This article explains it in detail. Here's a quick example:
<div
id="my-3d-viewer"
data-d8s-type="3d"
data-d8s-id="my-product"
></div>
* The "my-product" ID attribute refers to the SKU identifier used when creating the Product details in Dimensions. Set it to the one you'd like show
Configuration
The Viewer offers several parameters that help customize it to your requirements.
Viewer parameters can be set during initialization or using the update method. Next, we'll take a look at both.
Initialization
<html>
<head>
...
</head>
<body>
....
<script>
const d8sApi = initDimensions({
account: "my-account-name",
viewers: ["3D"],
threeDViewer: {
viewer: {
controls: {
position: "flex-start",
},
},
},
});
</script>
</body>
</html>
The threeDViewer.viewer properties are passed to the 3D Viewer when its rendered onto the page.
In this example, we're setting the position of the controls shown on the bottom of the viewer, moving them to the left:
Update
Once the Viewer is rendered, it is still possible to affect the various parameters that control the behavior and look&feel:
<script>
const d8sApi = initDimensions({ ... });
d8sApi.update3d(
document.getElementById("my-3d-viewer"),
{
controls: {
position: "center"
}
}
);
</script>
Result:
The update method expects to receive the container hosting the viewer as the first parameter. The second parameter is the object containing the viewer properties to update.
Note: There is no need to pass any of the params that were passed during initialization - the Viewer will merge the updated ones with those received before.
Reference
The following parameters control the behavior and look&feel of the Viewer. The values shown here are the defaults used:
{
//automatically show the iframe
autoShow: true,
//show the progress bar when loading
showLoadingProgress: true,
controls: {
//show the controls at the bottom of the viewer
enabled: true,
//where to place the button controls (css justify-content value)
position: "flex-end",
//whether to show the zoom +,- buttons
zoom: true,
//whether to allow mouse scroll-wheel zoom
mouseZoom: true,
//allow orbit controls rotate,
rotate: true,
//allow orbit controls pan,
pan: true,
},
rotation: {
//whether to enable rotation of the model
enabled: true,
//auto rotate speed
speed: 2,
//turn off rotation when user starts to interact with the model
offOnInteraction: false,
},
ar: {
//whether to show the AR view button
enabled: true,
//placement to use for (Android-only) AR viewer: "floor" or "wall"
placement: "floor",
//A name for the model. If present, it will be displayed in the UI (Android-only). The name will be truncated with ellipses after 60 characters.
title: "",
//A URL for an external webpage. If present, a button will be surfaced in the UI (Android-only) that intents to this URL when clicked.
link: "",
//Whether the model is resizable inside the (Android-only) AR view
resizable: true,
//a function that renders a custom overlay for the AR-QR code
customArQrRenderer: null,
},
styles: {
//"light", "dark", { custom }
theme: "light",
},
}
Theme Reference
The Viewer has two built-in themes: light & dark.
Light Theme
The light theme is appropriate to use when the hosting site/app uses a light background. It is used by default.
These are its values:
{
"bgPrimary": "#FFF",
"bgSecondary": "#D1D6E0",
"primary": "#000",
"secondary": "#888686",
"progress": "#3348c5",
"border": "#D1D6E0",
"borderHover": "#000",
"overlay": "rgba(10,12,15,0.25)",
"shadow": "rgba(33, 32, 32, 0.75)",
"bgHotspot": "#b4c9f3",
}
Dark Theme
The dark theme is appropriate to use when the hosting site/app uses a dark background.
These are its values:
{
"bgPrimary": "#000",
"bgSecondary": "#12171d",
"primary": "#FFF",
"secondary": "#dddddd",
"progress": "#0d9aff",
"border": "#3D475C",
"borderHover": "#FFF",
"overlay": "rgba(10,12,15,0.25)",
"shadow": "rgba(204,202,202,0.75)",
"bgHotspot": "#255ccc",
}
Custom
In case you'd like to change any or all of the colors used by the Viewer's theme, it's possible to pass an overriding object with the desired values to the styles.theme configuration parameter.
When passing a subset of the theme values, they will be merged with the light theme.