Shopify Integration Guide

Adding 3D to a Shopify site benefits brands and buyers alike, creating a more immersive and confident shopping experience while driving stronger business results.

Dopple Visual is designed to seamlessly integrate with your Shopify site and enables buyers to view selections in real-time through high fidelity 3D and augmented reality. Additional features such as Snapshot, personalization, and product animation further enhance the experience.

This guide describes how to embed Dopple Visual in a Shopify store.

Prerequisites

This guide assumes the following prerequisites are met:

• Content has been created in the Dopple Visual platform. Your client ID, as well as the product namespace and name are known.
• Your Shopify store has been added as an approved domain by Dopple.
• You have access to the product.
• The Shopify store uses a compatible theme. Compatible themes are the core Shopify themes as well as third party or custom themes that do not alter aspects of the variant selection scripts in theme.js, class names or element hierarchy in the media.liquid template, or class names or element hierarchy in the media section of the product-template.liquid template. Themes that alter these templates and scripts may still be compatible with or without minor revisions to the dopple-visual.liquid template.

Note

If the store is not using a compatible theme, there may be additional customization required to include the triggering of the required variantChange event.

Shopify with the Dopple Visual experience

A Shopify store with Dopple Visual integrated looks similar to any Shopify store. The key difference is the thumbnail that when selected will display a 3D model where the product media is normally displayed. In the example above, the thumbnail for Dopple Visual is the last thumbnail. After a brief loading time, the visual window can be rotated, zoomed, and panned and will reflect the selected product variant. Clicking on a media thumbnail other than the Dopple Visual thumbnail will display the media. The user can switch back and forth between normal media and Dopple Visual by selecting thumbnails; Dopple Visual will retain the configuration of the selected variant and the load will not occur again unless the page is reloaded.

Preparing the property mapping

The first step in adding Dopple Visual to a product page is to map the variants to Dopple Visual properties for the product. The mapping is a JSON file. An example mapping is shown below:

[
  {
    "shopifyOption": "option1",
    "mappedValues": {
      "Crocodile": [
        {
          "propertyName": "purse_material",
          "propertyValue": "purse_material_crocodile"
        },
        {
          "propertyName": "purse_crocodile_color",
          "propertyValue": [255,141,43]
        }
      ],
      "Evergreen": [
        {
          "propertyName": "purse_material",
          "propertyValue": "purse_material_crocodile"
        },
        {
          "propertyName": "purse_crocodile_color",
          "propertyValue": [28,73,40]
        }
      ],
      "Scarlet": [
        {
          "propertyName": "purse_material",
          "propertyValue": "purse_material_leather"
        },
        {
          "propertyName": "purse_leather_color",
          "propertyValue": [169,47,57]
        }
      ],
      "Magnolia": [
        {
          "propertyName": "purse_material",
          "propertyValue": "purse_material_leather"
        },
        {
          "propertyName": "purse_leather_color",
          "propertyValue": [213,173,169]
        }
      ]
    }
  },
  {
    "shopifyOption": "option2",
    "mappedValues": {
      "Gold": [
        {
          "propertyName": "purse_metal_color",
          "propertyValue": [253,214,162]
        }
      ],
      "Silver": [
        {
          "propertyName": "purse_metal_color",
          "propertyValue": [244,241,238]
        }
      ],
      "Gunpowder": [
        {
          "propertyName": "purse_metal_color",
          "propertyValue": [86,84,84]
        }
      ]
    }
  }
]

The mapping is an array of entries. Each entry has the following properties:

• shopifyOption – The name of the product option within the Shopify API. This will be option1, option2, and option3 for the first, second, and third options, respectively.
• mappedValues – A map of the values to be mapped for the option. The key in this map is the option value string. The value is an array of mappings. Note that this allows multiple property values to be set based on the value of a single option. This can be useful when the number of configurable product properties exceeds the maximum number of options in Shopify (currently 3), by allowing for multiple visual properties to be aggregated under a single option. Each mapping has the following properties.
  • propertyName is the name of the Dopple Visual property to be set when the user chooses this option.
  • propertyValue is the value to set for the Dopple Visual property. It can be a string value for a property that is a selection, a boolean value, or an array of 3 numbers 0-255 for a property that is a color.

Adding the metadata to the product

The next step in adding Dopple Visual to a product page is to add the required metadata to the product. Dopple Visual requires 4 metafields to be added to a product. The Shopify admin does not provide a way to edit metafields; however, there are good free apps available in the app store. This guide uses Metafy, but any metafield editor can be used.

In the metafield editor, add the following metafields to the product as shown below, using the namespace dopple.

• clientId – This is the Dopple-issued client id.
• productNamespace – This is the namespace for the product in the Dopple Visual platform.
• productName – This is the name of the product in the Dopple Visual platform.
• propertyMapping – The JSON snippet for the mapping discussed in the previous section.

Adding the trigger media to the product

As mentioned above, the display of Dopple Visual is triggered when the media associated with Dopple Visual is selected. In order to specify which media should be used to trigger the display of Dopple Visual, simply add dopple-visual-media-image as the alt for the media as shown below.

Adding the Dopple Visual Liquid Template

This step adds the code required for Dopple Visual to load and react appropriately to the media selection. The following template can be added to the theme of the Shopify store. We recommend creating an dopple-visual.liquid snippet and pasting in the liquid code below. With the preparation done in the previous steps, this code will work for any Shopify store that uses a compatible theme without modification.

<!-- Embed the Dopple Visual Component -->
<script src="https://builds.dopple.io/atlatl-visual-component/releases/current/index.js"></script>
<div class="doppleVisual">
    <atlatl-visual id="dopple-visual" client-id={{ product.metafields.dopple.clientId }}
    style="background: white; height: 400px; width: 400px">
        <av-product namespace={{ product.metafields.dopple.productNamespace }} name={{
      product.metafields.dopple.productName }}>
            <av-binding src="https://builds.dopple.io/atlatl-visual-component/releases/current/bindings/shopify/index.js"></av-binding>
        </av-product>
    </atlatl-visual>
</div>

<!-- Add the mapping from Shopify options to Dopple Visual properties -->
<script type="application/json" id="atlatl-visual-mapping">
    {{ product.metafields.dopple.propertyMapping }}
</script>

<!-- Capture the image id for the Dopple Visual media -->
{% assign dopple_visual_media_images = product.media | where: "alt", "dopple-visual-media-image" %}
{% if dopple_visual_media_images.size > 0 %}
    {% assign dopple_visual_media_image = dopple_visual_media_images[0] %}
    <script>
        doppleVisualMediaImageId = "{{ dopple_visual_media_image.id }}"
    </script>
{% endif %}

<!-- Capture the current variant so the binding can use it -->
<script>
    {% assign current_variant = product.selected_or_first_available_variant %}
    atlatlCurrentVariant = "{{ current_variant.title }}"
</script>

<!-- Embed Dopple Visual so that it is shown when the thumbnail corresponding to Dopple Visual is selected and hidden when a different thumbnail is selected -->
<script>
    function initDoppleVisual() {
        var thumbnails = document.querySelector('.thumbnails-wrapper');
        var doppleVisual = document.querySelector('.doppleVisual');
        var imageTemplates = document.querySelectorAll('.product-single__media-wrapper');
        var doppleVisualThumbnail = doppleVisualMediaImageId ? document.querySelector(`[data-thumbnail-id='product-template-${doppleVisualMediaImageId}']`) :
        thumbnails.querySelector('.product-single__thumbnails-item:last-child .product-single__thumbnail');
        var doppleVisualMedia = document.querySelector(`[data-media-id='${doppleVisualThumbnail.getAttribute('data-thumbnail-id')}']`);
        var doppleVisualThumbnailImage = doppleVisualThumbnail.querySelector('.product-single__thumbnail-image');

        doppleVisual.style.display = 'none';

        // Event handler for handling selection of a thumbnail other than the one associated with Dopple Visual.
        function onThumbnailSelected(event) {
            if (event.target != doppleVisualThumbnailImage) {
                doppleVisual.style.display = 'none';
                // unhide doppleVisualMedia so there is a media wrapper without hide which is required for the Shopify switch media logic.
                doppleVisualMedia.classList.remove('hide');
                // Remove the event listener as it is not needed again until the Dopple Visual thumbnail is selected.
                thumbnails.removeEventListener('click', onThumbnailSelected, true);
            }
        }

        // Hides all media.
        function hideImages(imageList) {
            imageList.forEach(image => {
                image.classList.add('hide');
            })
        }

        // Shows Dopple Visual.
        function showDoppleVisual() {
            // Display Dopple Visual.
            doppleVisual.style.display = 'block';

            // Hide the other product media.
            hideImages(imageTemplates);

            // Register a listener that will fire in the capture phase. We need to make sure this fires before the Shopify event handler, hence the use of a capture listener.
            // This listener will ensure that the media is in the state that is expected by the Shopify event handler.
            thumbnails.addEventListener('click', onThumbnailSelected, true);
        }

        // Add an event listener to the Dopple Visual thumbnail to show Dopple Visual when it is clicked.
        if (doppleVisualThumbnail) {
        doppleVisualThumbnail.addEventListener('click', () => {
            // Delay execution of this event to ensure that the Shopify event handler fires first.
            setTimeout(showDoppleVisual, 0);
        });
        }
    }

    // Defer Dopple Visual initialization until the DOM is loaded.
    window.addEventListener('DOMContentLoaded', initDoppleVisual);
</script>

Adding a reference to the Dopple Visual snippet

The final step is to include the Dopple visual snippet created above in the store’s theme. We recommend doing this in the product-template.liquid section inside of the single product media group above the thumbnails as shown in the example below:

<div class="grid product-single{% if section.settings.enable_payment_button %} product-single--{{ section.settings.media_size }}-media{% endif %}">
    <div class="grid__item product-single__media-group {{ product_media_width }}{% if section.settings.media_size == 'full' %} product-single__media-group--full{% endif %}" data-product-single-media-group>
        {%- assign featured_media = product.selected_or_first_available_variant.featured_media | default: product.featured_media -%}

        {%- for media in product.media -%}
            {% include 'media', media: media, featured_media: featured_media, height: height, enable_image_zoom: enable_image_zoom, image_zoom_size: product_image_zoom_size, image_scale: product_image_scale %}
        {%- endfor -%}
        
        <noscript>
            {% capture product_image_size %}{{ height }}x{% endcapture %}
            <img src="{{ featured_media | img_url: product_image_size, scale: product_image_scale }}" alt="{{ featured_media.alt }}" id="FeaturedMedia-{{ section.id }}" class="product-featured-media" style="max-width: {{ height }}px;">
        </noscript>

        {%- include 'dopple-visual' -%}
    </div>
</div>

This is the only content in the theme that needs to be altered to integrate Dopple Visual.

Testing the store

With all of the prerequisites and steps above completed, the final step is to test the store. We recommend verifying the following:

• Verify the store loads and displays the media correctly on the product page.
• Select the thumbnail associated with Dopple Visual. Verify the media viewer switches to Dopple Visual. Note it may take a few seconds for the product to load.
• Verify that the user can zoom, rotate and pan the product in Dopple Visual.
• Verify that the product responds to variant selections correctly.
• Verify that the other product media is displayed and Dopple Visual is hidden when the appropriate thumbnail is selected.
• Verify Dopple Visual can be displayed at will by selecting the thumbnail associated with Dopple Visual.

Summary

In this guide, we described how to integrate Dopple Visual with a Shopify store. We described the experience of an integrated Dopple Visual, the prerequisites, the steps needed, and how to verify the integration. Once verified, the site is ready to go live, and the store customers can enjoy their shopping experience enhanced by Dopple Visual 3D visualization.