Shopify Integration

Dopple can be integrated into Shopify storefronts by following one of two approaches:

Using the official Dopple App for Shopify; or
Manually setting up a vanilla Shopify integration (no app)

Prerequisites

Your Shopify store is using a compliant theme: a store with at least an Online Store 2.0 theme.
You have a valid owner, workspace, project name, and version ready for use.
You know the configuration properties and values available on your 3D product (typically found in the editor from Dopple).
You have at least one product created in your Shopify store.

Ensure that Dopple has also whitelisted any domains that you plan to view or test your 3D products on, including any subdomains and any port numbers, if applicable (wildcards are also permitted).

For example:

https://www.mysite.com
https://staging.mysite.com
https://*.mysite.com
http://localhost:1234
http:127.0.0.1:5173

Integration Using the Dopple Shopify App

The Dopple Shopify app is designed to provide an easy way for store owners to “map” their products’ variants to their corresponding Dopple values. It acts as a bridge between your existing Shopify product options and the Dopple 3D asset properties.

App Installation

Visit the Shopify App Store to view and install the Dopple app on your Shopify storefront.

App Setup and Data Generation

Global Settings

Once the Dopple app has been installed, you will first need to configure your Dopple “owner” value, along with a default workspace value to use for your products. Ensure “Dopple (V2)” is selected to access the latest API features (V1 is now deprecated and will be removed in future versions).

If you are adding custom CSS or hooking into the Dopple instance with any custom JavaScript, you can also optionally set a custom class and ID to use on the Dopple canvas’s container element here as well.
Product-level Configuration

Within the Dopple app, Navigate to the Products table and set up your variant map for any products available on your store:
- Fetch Config: Enter the Project Name and Version, then click “Fetch” to retrieve all available 3D properties and options directly from Dopple.
- Property Mapping: Map your Shopify option names (e.g. “Frame Color”) to the 3D property names (e.g. frameColor).
- JSON Generation: The app will output a variantMap JSON object. This object is injected into the page via app blocks (Visual or Data-Only).
App Block Setup

Once a variant map has been created for a product, you may either copy it directly to use in your product’s page template as needed or embed it automatically using the Dopple App Block. The Dopple App Block is ideal, as it will ensure the page always loads the latest variant mapping for that product.
1. On your storefront, navigate to Online Store > Edit Theme.
2. On your Product Page template, add one of the two Dopple App Blocks:
  - PDP 3D Product — This will include the Dopple canvas in your page that the 3D product will be rendered onto, along with the doppleShopify object on the global window for you to access the variant mapping.
  - PDP 3D Product: Data Only — This will include only the doppleShopify object on the global window; no 3D canvas on the page itself.

Front-end Implementation

Once an App Block has been added to your page, the variant map can be accessed on the window via window.doppleShopify.productConfig.v2VariantMapping.variantMap.

Using this map, you can easily set up event listeners on any necessary elements on your page to get the selection object that corresponds with the option that the user just chose, and call dopple.updateSelection() accordingly.

Example: Bicycle Product Mapping

The following is an example of the variantMap JSON generated by the app for a configurable bicycle. This object maps the human-readable Shopify options to the hard-coded values on the 3D asset in the Dopple platform.

[
  {
    "group": "Frame Color",
    "variants": [
      {
        "variantName": "Crimson",
        "selection": {
          "bicycle-frame": "crimson"
        }
      },
      {
        "variantName": "Neon",
        "selection": {
          "bicycle-frame": "neon"
        }
      },
      {
        "variantName": "Electric Blue",
        "selection": {
          "bicycle-frame": "electric-blue"
        }
      }
    ]
  },
  {
    "group": "Decal Design",
    "variants": [
      {
        "variantName": "Solid",
        "selection": {
          "logo-outline": "solid",
          "logo-fill": "solid"
        }
      },
      {
        "variantName": "Stripes",
        "selection": {
          "logo-outline": "dotted",
          "logo-fill": "diagonal-stripes"
        }
      }
    ]
  }
]

First, make sure your ecommerce frontend has markup that indicates the groups and variants you’ve set up.

Your exact setup may differ, but the example below uses a data-variant-group attribute to indicate a variant group, and the value attribute on each <option> indicates the variant’s name.

<select id="color-selection" data-variant-group="Frame Color">
  <option value="Crimson">Crimson</option>
  <option value="Neon">Neon</option>
  <option value="Electric Blue">Electric Blue</option>
</select>

const variantMap = window.doppleShopify.productConfig.v2VariantMapping.variantMap
const colorSelect = document.getElementById('color-selection')

// Update the 3D bike product's color whenever the `<select>` element is changed
colorSelect.addEventListener('change', async (event) => {

  // Get the variant group value (based on its `data-variant-group` attribute)
  const group = colorSelect.dataset.variantGroup

  // Get the selected color
  const variantName = event.target.value

  // Find the corresponding `selection` object for the selected color
  const selection = variantMap
    .find((item) => item.group === group)?.variants
    .find((variant) => variant.variantName === variantName)?.selection

  // Call `dopple.updateSelection()` to update the 3D product
  if (selection) {
    await dopple.updateSelection(selection)
  }
})

Third Party App Recommendations

Because Dopple’s app is only meant to provide an easy way to map variants to their corresponding values on the configurable 3D asset, it is recommended that you use any additional third-party apps as needed for setting up other aspects of your storefront’s products, such as:

Adding variants beyond Shopify’s built-in limits
“Bundling” products to allow for multiple SKUs on a single product page
Setting up conditional logic in your UI
Handling pricing, inventory management, and add-to-cart functionality

The “right” app for you will vary depending on your storefront’s unique needs, but the table below lists a number of options that may work well for many common 3D configurator experiences and Shopify setups:

Shopify App Name	Price	Unlimited Variants	Conditional Logic	Bundles
Avis Product Options	Free + Premium	Yes	Yes	Yes
Globo Product Options	Free + Premium	Yes	Yes	Yes
Infinite Product Options	Free + Premium	Yes	Yes	Yes
Zepto Product Personalizer	Free + Premium	Yes	Yes	No
Qikify Custom Product Options	Free + Premium	Yes	Yes	Yes
Hulk Product Options	Free + Premium	Yes	Yes	Yes
Advanced Product Options	Free + Premium	Yes	Yes	Yes
OPTIS Product Options, Variant	Free + Premium	With Premium	Yes	Yes

Integration Without the App

While using the Dopple Shopify app is strongly recommended for most storefronts, it is not strictly required. If needed, custom integrations can be set up without using the Dopple app, following the information and steps below.

Adding Owner and Workspace Metadata

Adding Metaobject Definitions

Login to your Shopify admin account, and in the left-hand menu navigate to Settings > Custom Data > Metaobjects.
On the Metaobjects page, click the “Add Definition” button to create a new metaobject definition, and enter dopple for the name/type.
Add two fields:
- Field 1: Workspace
  Key: dopple.workspace
  Type: Single line text (or another appropriate type)
  Validation: Mark as Required
- Field 2: Owner
  Key: dopple.owner
  Type: Single line text (or another appropriate type)
  Validation: Mark as Required
Click “Save” to create the metaobject definition.

Adding a New Entry to the Metaobject

Navigate to Custom Data > Metaobjects and select the metaobject definition (dopple) you just created.
Click the “Add Entry” button to create a new entry, and fill in the required fields:
- Workspace: Enter the workspace name provided by Dopple.
- Owner: Enter the owner’s name provided by Dopple.
Update the Handle name to doppledata to identify the entry as a Dopple entry.
Click “Save” to finish creating the entry.

Creating Metadata Fields for Products and Variants

Adding Product Name and Version Metadata

Access the metafield definitions page for your products by navigating to Settings > Custom Data > Products in your Shopify admin.
Create a new metafield for your Dopple product’s name by clicking the “Add Definition” button and entering the following fields.
- Name: Enter a descriptive name for this field, such as “Dopple Product Name”.
- Namespace and key: Enter dopple.productName.
- Content type: Select Single line text.
Create second new metafield for your Dopple product’s version with the following fields.
- Name: Enter a descriptive name, such as “Dopple Product Version”.
- Namespace and key: Enter dopple.productversion.
- Content type: Select Single line text.
Click “Save” to create the new metafields for your product.

Adding Metadata for Variants

In the Custom Data section, select Variants. This will open the page where you can manage metafield definitions for products.
Click the Add definition button at the top-right corner to create a new metafield definition, and fill out the following fields:
- Name: Enter a descriptive name for the metafield. For example, “Dopple Mapping”.
- Namespace and key: Enter dopple.mapping.
- Content type: Select JSON.
Click “Save” to create the new metafield definition.

Steps to Configure Metadata and Variant Mapping for Products

To begin mapping your product metadata and variants to your 3D Dopple product, follow these steps:

Go to the Products section in Shopify and select the product to configure.
In the Metafields section, enter the following details provided by Dopple:
- Dopple Product Name: Enter the product name (example: my-boat-product).
- Dopple Product Version: Enter the product version.
Add or edit a variant in the Variants section of the product, and locate the Dopple Mapping field in the Metafields section for the variant. Then, enter the choice-option mapping in JSON format:
```
{
  "choice1": "opt1",
  "choice2": "opt2"
}
```
For example, if the choices for a variant are Size and Color, and the options are Large and Red, the mapping should be:
```
{
  "Size": "Large",
  "Color": "Red"
}
```

Adding Dopple to Your Site Pages

From your Shopify store’s dashboard, navigate to Online Store > Themes > Customize to begin adding Dopple content blocks to pages on your site. In the Sections panel, click on Custom Liquid and add the following Liquid code to include the Dopple 3D object on your product page.

{% assign dopple_metaobject = shop.metaobjects.dopple.doppledata %}
{% assign product_metafield = product.metafields.dopple %}

<div id="containerEle" style="height: 300px; position: relative;"></div>
<style>
  #containerEle div {
    display: block !important;
  }
</style>
<script>
  document.addEventListener('DOMContentLoaded', async function () {
    // Ensure the canvas exists before running the script
    const container = document.getElementById('containerEle');
    if (container) {
      console.log('Container ready for rendering');
    }

    const productVariants = [
      {% for variant in product.variants %}
        {
          "mapping": {{ variant.metafields.dopple.mapping | parse_json }},
          "variantId": "{{ variant.id | escape }}",
        }
        {% if forloop.last == false %},{% endif %}
      {% endfor %}
    ];

    const mappedVariant = productVariants.reduce((acc, variant) => {
        acc[variant.variantId] = { ...variant };
        return acc;
    }, {});

    // Access and log product metafield
    const doppleObj = {
      owner: '{{ dopple_metaobject.owner | escape }}',
      workspace: '{{ dopple_metaobject.workspace | escape }}',
      productName: '{{ product_metafield.productName | escape }}',
      productVersion: '{{ product_metafield.productversion | escape }}',
      productVariants
    };

    const productform = document.querySelector("product-form");

    console.log('Dopple Metaobject Fields:', doppleObj);

    const { DoppleXR } = await import(
      "https://builds.dopple.io/packages/dopple-sdk@latest/dopple-sdk.js"
    );

    const sessionId = window.crypto.randomUUID();

    const dopple = new DoppleXR({
      container,
      selection: {},
      owner: doppleObj.owner,
      workspace: doppleObj.workspace,
      projectName: doppleObj.productName,
      productVersion: doppleObj.productVersion,
      logNamespace: "sdk",
      sessionId
    });

    await dopple.load();

    const selectedVariantId = productform.querySelector('input.product-variant-id')?.value;

    const selected = Object.entries(dopple.matrix.choices).reduce(
      (acc, [key, value]) => {
        if(mappedVariant[selectedVariantId].mapping.hasOwnProperty(key)) {
          acc[key] = mappedVariant[selectedVariantId].mapping[key] || Object.keys(value.options)[0];
        } else {
          acc[key] = Object.keys(value.options)[0];
        }
        return acc;
      },
      {},
    );

    await dopple.updateSelection(selected);

    dopple.run();

    const canvas = document.querySelector('canvas'); // Ensure you select the correct canvas

    productform.addEventListener("change", function (event) {
      const currentVariantId = event.target.value; // Leather, Black, etc.
      const { mapping: doppleMapping } = mappedVariant?.[currentVariantId];

      for(const choice in doppleMapping) {
        selected[choice] = doppleMapping[choice];
      }
      dopple.updateSelection(selected);
    });

  });
</script>

For now, we are using Custom Liquid to add the 3D object to the page. In the future, we plan to create an extension to simplify this process.