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

Creating and initializing 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.

Creating and loading 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.

Creating the Product instance​

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

const product = new Atlatl.Product(template)

Then, awaiting product.ready() will signal when the product is fully ready. At this point, it is common to hide the loading screen or kick off any other interactions in the UI to display the product.

// Hide the loading screen to show the product once the product is ready
await myProduct.ready()
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.

Destroying the Visual instance​

Before any new instances of Dopple Visual are initialized on a page, the first instance should be destroyed using Visual’s destroy() method.

This will return a Promise that will be resolved when the Visual instance has been destroyed. 

await visualInstance.destroy()

console.log('Visual instance destroyed. It is now safe to create a new instance.')

As an extra check, the destroyed property on the Visual instance can be used to ensure that the instance has been fully destroyed.

console.log(visualInstance.destroyed) // true
tip

If you are using Dopple in an SPA — such as a React or Vue site — be sure to destroy the Visual instance when its component is unmounted, such as when the user navigates to a different page/route.

Otherwise, the Visual instance will continue to run in the background, consuming resources and potentially causing conflicts with new instances.

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>
        <!-- Button to destroy the Dopple Visual instance -->
        <button id="destroy-button">Destroy</button>
    </body>
</html>