Getting Started
Prerequisites
- An authorized domain
Dopple Visual will only work on your domain (e.g.www.your-website.com) once it has been authorized by Dopple. This prevents your assets from being served on other websites outside your control. Dopple will work with your team to authorize all live and staging domains needed for your implementation. - Completed art assets
Dopple will work with you to create and prepare the art assets to be displayed in your product configurator/visualizer. This includes all models, materials, textures, and environments for your product. - Configurability matrix
Once your art assets are ready, Dopple will provide you with a configurability matrix detailing the pre-defined properties and values that can be updated by your site’s front-end (for example, by a user clicking a button in your UI). - Client ID, product name, and namespace
To display a 3D configurator or visualizer on your site, Dopple Visual requires a validclient-id, productname, and productnamespace(each of which will be provided to you by Dopple).
Visual Component vs. direct API implementation
As you prepare to add Dopple Visual to your site, you will have two primary methods of implementation:
“Automatically” via the Visual Component.
The Visual Component is the recommended method for 99% of use cases, and provides developers with a ready-made 3D configurator/visualizer web component (along with built-in features like augmented reality, snapshots, and fullscreen mode) without the manual setup steps needed for the Visual API.
Visual Component docsDirectly via the Visual API.
The Visual API is available for uncommon edge cases, where developers need extremely nuanced control over the 3D implementation on their page. In this method, developers must create the
Visual API docs<canvas>element on their page and manually call the necessary JavaScript functions to initialize Dopple Visual and its features.
Below is an example of the code required to initialize a 3D product using each method:
- Visual Component
- Visual API
<html>
<head>
<meta charset="utf-8">
<title>My Page</title>
<!-- Link to the Visual Component's scripts -->
<script src="https://builds.dopple.io/atlatl-visual-component/releases/current/index.js" defer></script>
</head>
<body>
<!-- The Visual Component -->
<atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
<av-product namespace="my_namespace" name="my_product_name"></av-product>
</atlatl-visual>
</body>
</html>
<html>
<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>
</head>
<body>
<!-- Canvas to render the 3D product onto -->
<canvas id="my-canvas"></canvas>
<script>
let visual
let myProduct
let namespace = 'my_namespace'
let name = 'my_product_name'
// Initialize Dopple Visual and load the product once the document is ready
window.addEventListener('load', async () => {
const renderCanvas = document.getElementById('my-canvas')
visual = new Atlatl.Visual(renderCanvas)
// Replace with your client ID here
await visual.initClient('a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5')
// Create and load the ProductTemplate
const template = new Atlatl.ProductTemplate(visual, namespace, name)
await template.load()
// Create the Product instance
myProduct = new Atlatl.Product(template)
// Hide the loading screen to show the product once the product is ready
await myProduct.ready()
visual.loadingScreen.hide()
})
</script>
</body>
</html>
Note
A “hybrid” of both implementation methods (the Visual Component and the Visual API) may also be used. For example, you can use the Visual Component to handle the primary display and functionality of the 3D product, and then access the API through the Visual Component for more nuanced control.
Sizing Dopple Visual within your page layout
The <canvas> element that Dopple renders the 3D product onto (or the <atlatl-visual> element, if using the Visual Component) is designed to be fluid in width and height, allowing it to grow or shrink to fill the space within your UI.
For this reason, it is important to give Dopple an explicit CSS width/height or wrap Dopple inside of a container element with some explicit width and height, instead of purely using percentage-based heights.
- Visual Component
- Visual API
<!-- Set explicit heights on Dopple itself -->
<atlatl-visual style="height: 600px; width: 800px;"></atlatl-visual>
<!-- Or, set explicit heights on Dopple's container -->
<div style="height: 600px; width: 800px;">
<atlatl-visual style="height: 100%; width: 100%;"></atlatl-visual>
</div>
<!-- Set explicit heights on Dopple itself -->
<canvas id="dopple" style="height: 600px; width: 800px;"></canvas>
<!-- Or, set explicit heights on Dopple's container -->
<div style="height: 600px; width: 800px;">
<canvas id="dopple" style="height: 100%; width: 100%;"></canvas>
</div>
For example, here is the CSS sizing used on many of the Dopple demos’ UIs.
<atlatl-visual id="dopple-visual"></atlatl-visual>
#dopple-visual {
background: #FFF;
cursor: grab;
height: calc(100vh - 10rem);
max-height: 56rem;
width: 100%;
}
caution
Without an explicit CSS height on either Dopple or one of its containers (i.e. Dopple or each of its containers up to the <body> all have flexible or percentage-based heights), the <canvas> element may get stuck in an infinite-resizing loop, which may cause performance issues or crashing.
The configurability matrix
Once your 3D assets are finished and ready for the web, Dopple will provide a comprehensive list of all the configurable properties and values available on your 3D product in a configurability matrix.
For example, a basic configurability matrix for a sofa product may look like this:
| Name | Property | Value | Type |
|---|---|---|---|
| Style – Loveseat | sofa_style | loveseat | Mesh Swap |
| Style – Two-seater | sofa_style | two_seater | Mesh Swap |
| Style – Three-seater | sofa_style | three_seater | Mesh Swap |
| Material – Leather | sofa_material | material_leather | Material Swap |
| Material – Fabric | sofa_material | material_fabric | Material Swap |
| Color – Leather | sofa_leather_color | [255, 255, 255] | RGB Color |
| Color – Fabric | sofa_fabric_color | [255, 255, 255] | RGB Color |
Name
Description: An arbitrary name/descriptor of the configurable property. The “name” column is optional, and only used for your convenience when locating the property and value fields.
Property
Description: A string, which is the hard-coded ID of the property on the product to be configured.
- If you are using the Visual Component’s automatic DOM binding, this will be the value used for the
data-av-propertyattribute. - If you are using the API directly, this will be the first parameter passed to the API’s
setValue()method (e.g.setValue(property, value)).
Value
Description: Either a string, a boolean (true or false), or an array of RGB values (e.g. [255, 0, 123]) that the corresponding property field may be set to.
If the property is set up to accept an array of RGB values, then the property may be set to any valid RGB color — not just the ones defined in the configurability matrix. Otherwise, if the property accepts a string, then only one of the predefined strings listed in the configurability matrix may be passed to this property.
- If you are using the Visual Component’s automatic DOM binding, this will be the value used for the
data-av-valueattribute. - If you are using the API directly, this will be the second parameter passed to the API’s
setValue()method (e.g.setValue(property, value)).
Type
Description: A descriptor of what type of configuration the property is for. The “type” column is optional, and only used for your convenience when locating the property and value fields.