Skip to main content

Getting Started

Prerequisites

  1. 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.
  2. 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.
  3. 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).
  4. Client ID, product name, and namespace
    To display a 3D configurator or visualizer on your site, Dopple Visual requires a valid client-id, product name, and product namespace (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:

  1. 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 docs
  2. Directly 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 <canvas> element on their page and manually call the necessary JavaScript functions to initialize Dopple Visual and its features.

    Visual API docs

Below is an example of the code required to initialize a 3D product using each method:

index.html
<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>
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.

<!-- 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>

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:

NamePropertyValueType
Style Loveseatsofa_styleloveseatMesh Swap
Style Two-seatersofa_styletwo_seaterMesh Swap
Style Three-seatersofa_stylethree_seaterMesh Swap
Material Leathersofa_materialmaterial_leatherMaterial Swap
Material Fabricsofa_materialmaterial_fabricMaterial Swap
Color Leathersofa_leather_color[255, 255, 255]RGB Color
Color Fabricsofa_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-property attribute.
  • 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-value attribute.
  • 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.

  • Mesh swap replaces the product’s mesh with a different mesh.
  • Material swap replaces the material applied to the model with a different material.
  • RGB color changes the albedo color of the currently applied material.