Migration Guide

Migrating 3D products on your website from using the previous version of Dopple (Dopple Visual) to the new Dopple platform is fairly straightforward. Before you begin updating your site, you will need a published product set up in the Dopple platform; specifically, the owner, workspace, projectName, and productVersion values.

Looking to upgrade but don’t have your products migrated to the new platform yet? Let us know — our team will be happy to help!

Many of the fields that were used to initialize Dopple in Dopple Visual are still used in the new Dopple platform, but with slightly different names. For example, clientId was a UUID for each organization, but now owner is a simple ID with your organizations name.

See the table below to see each new field’s equivalent name:

Dopple Visual old	Dopple Platform new
`clientId`	`owner`
`namespace`	`workspace`
`name`	`projectName`
`version`	`productVersion`

Migration Steps

Dopple Visual had two ways of being implemented on a page: the Visual API or the Visual Component. Refer to the Dopple Visual documentation for more information on each.

Visual Component Migration

The Visual Component was a custom web element that allowed for easily adding Dopple’s 3D products to your webpages without the need for any custom JavaScript.

Remove the <script> tag for the Visual Component’s scripts, and create a new module script on your page to import Dopple.

<html>
    <head>
       <script src="https://builds.dopple.io/atlatl-visual-component/releases/current/index.js"></script>
       <script type="module">
           import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";
       </script>
    </head>
    <body>
        <atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
            <av-product namespace="my_namespace" name="my_product_name" version="1"></av-product>
        </atlatl-visual>
    </body>
</html>

Remove the Visual Component (the <atlatl-visual> tag), and replace it with a new element to act as the Dopple container, adding any necessary classes or styling to maintain the same appearance on your page.

<body>
   <atlatl-visual client-id="a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5">
       <av-product namespace="my_namespace" name="my_product_name" version="1"></av-product>
   </atlatl-visual>
   <div id="dopple-container"></div>
</body>

In your module script, initialize a new DoppleXR instance, passing in the necessary values for your new product. See the Basic Usage page for more information.

<script type="module">
    import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";

   const dopple = new DoppleXR({
       container: document.getElementById("dopple-container"),
       owner: "my-org",
       workspace: "my-workpsace",
       projectName: "My Project",
       productVersion: "1",
       selection: {}
   });

   await dopple.load();
   dopple.resize({ trackParentSize: true });
   dopple.run();
</script>

If you used the Visual Component’s DOM binding attributes to automatically connect elements in your UI to control and update the 3D product, you will need to remove those attributes and set up event listeners on your elements to call dopple.updateSelection() manually.

<!-- Button binding -->
<button data-av-property="product_color" data-av-value="red">
    Red
</button>

<!-- Radio binding -->
<div data-av-property="product_color">
    <label>
        <input type="radio" name="product_color" data-av-value="red" checked />
        Red
    </label>
    <label>
        <input type="radio" name="product_color" data-av-value="blue" />
        Blue
    </label>
</div>

<!-- Select menu binding -->
<select data-av-property="product_color">
    <option data-av-value="red">Red</option>
    <option data-av-value="blue">Blue</option>
    <option data-av-value="yellow">Yellow</option>
    <option data-av-value="green">Green</option>
</select>

If you used the Visual Component’s Embedded UI to add icon buttons over your canvas for AR, snapshots, or fullscreen mode, you will need to manually set those up. See the pages below for guides and code snippets to make this setup easy:

Visual API Migration

The Visual API was Dopple’s manual method of integration, requiring more custom JavaScript up front but giving developers maximum control over their 3D visual experience.

Remove the <script> tag for the Visual API’s scripts, and create a new module script on your page to import Dopple.

<html>
    <head>
       <script src="https://builds.dopple.io/atlatl-visual-api/releases/current/index.js"></script>
       <script type="module">
           import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";
       </script>
    </head>
    <body>
        <canvas id="dopple-canvas"></canvas>
    </body>
</html>

Remove the <canvas> element used to render the 3D product, and replace it with a new element to act as the Dopple container, adding any necessary classes or styling to maintain the same appearance on your page.
```
<body>
   <canvas id="dopple-canvas"></canvas>
   <div id="dopple-container"></div>
</body>
```

Remove your previous Dopple initialization script, and initialize a new DoppleXR instance in your new module script, passing in the necessary values for your new product. See the Basic Usage page for more information.

 <script>
    const renderCanvas = document.getElementById("my-canvas")
    const visual = new Atlatl.Visual(renderCanvas)
    await visual.initClient("a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5")

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

    const myProduct = new Atlatl.Product(template)
    await myProduct.ready()

    visual.loadingScreen.hide()
 </script>

<script type="module">
    import { DoppleXR } from "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js";

   const dopple = new DoppleXR({
       container: document.getElementById("dopple-container"),
       owner: "my-org",
       workspace: "my-workpsace",
       projectName: "My Project",
       productVersion: "1",
       selection: {}
   });

   await dopple.load();
   dopple.resize({ trackParentSize: true });
   dopple.run();
</script>

Update event any listeners on elements in your UI to use dopple.updateSelection() instead of product.setValue().

<button id="color-red">Red</button>

<script>
    const myButton = document.getElementById("color-red");
    myButton.addEventListener("click", () => {
       await product.setValue("product_color", "red");
       await dopple.updateSelection({ "product_color": "red" });
    });
</script>

If you used the Visual API’s AR or snapshot features, you will need to manually update those to use the new Dopple methods. See the pages below for guides and code snippets to make this setup easy:

Analytics Events

If you used any of Dopple’s custom analytics events, such as tracking $addToCart or other conversion events, remove those scripts from your page. Analytics will be coming to the new Dopple platform soon, with full guides on how to set up custom event tracking once it’s released.

<html>
    <head>
       <script type="module" src="https://builds.dopple.io/dopple-utilities/releases/current/index.js" defer></script>
    </head>
    <body>
       <button id="add-to-cart-button">Add to Cart</button>
       <script>
           // Get the "Add to Cart" button
           const myButton = document.getElementById('add-to-cart-button')

           // Send the custom analytics event to Dopple when "Add to Cart" is clicked
           myButton.addEventListener("click", () => {
               const visual = document.querySelector("atlatl-visual")
               visual.analytics.sendCustomEvent("$addToCart")

               await window.Dopple.sendOrderEvent(
                   "a1a1a1a1-b2b2-c3c3-d4d4-e5e5e5e5e5e5",
                   /* order data object here */
               )
           })
       </script>
    </body>
</html>