Skip to main content

Basic Usage

Implementing Dopple Visual on your site​

Dopple requires an HTML canvas element in the location on the page where where the 3D visual is to be displayed:

<canvas id="renderCanvas" touch-action="none" width="800" height="600"></canvas>
Note

We recommend including touch-action="none" in order to have gestures work properly on mobile/touch devices. Other properties in the example are not required.

Script tag​

Include a script tag the references the Dopple Visual API:

<script src="https://builds.dopple.io/atlatl-visual-api/releases/current/index.js"></script>

Older releases can be specified instead of current.

Create and initialize the Visual instance​

Once the DOM is loaded the Visual instance can be created. This will provide access to the Visual API.

window.addEventListener('load', async () => {
visualInstance = new Atlatl.Visual(document.getElementById('renderCanvas'))

const initOptions = {
backgroundColor: [255, 255, 255, 0]
};

await visualInstance.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5', initOptions)
})

The Dopple Visual instance can be created with either a reference to an HTMLCanvasElement or an ID of a canvas element on the page. For more information, see the API reference for Visual. Once created, the Visual instance needs to be initialized with the client and any initial options. The client ID will be provided by Dopple. This ID provides authorization to access visual content as long as the initClient call is made from the domain registered for that client. It can be thought of as an API key, and should be protected as such. The host site may want to provide the client ID value at runtime from the server rather than having it statically on the page.

The options that can be included with the initClient call are described here.

  • The background color is used to set the color of the scene as an RGB value with an alpha. The setting in the example would result in a transparent background, allowing the background color or image of the canvas to show behind the product.
  • The showLoadingScreen option specifies whether to show the default loading screen. This defaults to true. Note that the loading screen must be explicitly hidden, once shown. If a loading screen is not displayed, then the content of the scene will be visible as the product loads.

Create and load the ProductTemplate​

Once the Visual instance has been created, it can be used to create the ProductTemplate. For more information see the ProductTemplate API reference.

const namespace = 'my_namespace'
const name = 'my_product_name'
const version = 1

const template = new Atlatl.ProductTemplate(visualInstance, namespace, name, version)
await template.load()

The ProductTemplate constructor requires the Visual instance, as well as the Configurable Item’s (CI) namespace and name, and an optional CI version number. The CI namespace and name should be provided by the implementation and uniquely identify the product that will be created from the template.

tip

Omitting the version will load the current version of the Configurable Item.

Loading the ProductTemplate will load the assets required for the initial display of the product. The load method returns a Promise that will be resolved when the assets required for initial display have loaded. Dopple Visual will continue to load final quality assets in the background and will silently replace the initial quality assets with final quality when they are available.

Create the Product instance​

Once the template has loaded, it can be used to create the Product instance. This will begin the display of the product in the canvas.

const product = new Atlatl.Product(template)
visualInstance.loadingScreen.hide()
info

Note that if showLoadingScreen was not explicitly set to false when the Visual instance was created, it will need to be hidden in order for the product to be visible in the canvas.

Full code example​

index.html
<html lang="en">
<head>
<meta charset="utf-8">
<title>My Page</title>
<!-- Link to the Visual API's scripts -->
<script src="https://builds.dopple.io/atlatl-visual-api/releases/current/index.js" defer></script>
<!-- Link to custom scripts -->
<script src="scripts.js" defer></script>
</head>
<body>
<!-- Canvas to render the 3D product onto -->
<canvas id="my-canvas"></canvas>
</body>
</html>