360 HD Viewer - Shopify Implementation

In this guide we will implement the Cylindo 360 HD Viewer into a webshop running the Shopify platform. But before we start the installation, it is important to start with some information about Shopify's scope in terms of products, options and variants. This is needed because by default Shopify uses a different structure than Cylindo to store product information so third-party applications are needed to resolve these differences. So let’s start with this article as it talks about the product details in Shopify. For each product, Shopify users are able to store some information such as Title, Description, Media, Price, Cost, SKU, Barcode and Variants etc.

 

In Shopify, when a product is set to have different values for each option such as multiple Upholstery or Legs Types, Shopify's core generates all the possible combinations with the available options and each combination is named variant and each variant is now distinguished using a unique ID internally and allow users to set a unique SKU code for it. More information about variants can be found here.

 

At this point it is important to mention the first important difference between Cylindo and Shopify products. While Shopify’s core generates a unique key for each variant, in Cylindo products have a unique product code for all possible combinations, Cylindo products do not handle unique IDs or SKU codes for each possible variant or combination. In Cylindo products, the variants are handled through feature types and options. A feature type defines an attribute of the product that can be changed or customized. It could be Color, Upholstery, Legs/Frames, Arms, Headrest etc. And the options are all the possible values for each feature type, for example Wood Legs, Metal Legs, Plastic Legs etc.

 

Since by default there is no space to store the codes needed by Cylindo for the product, features and options, they have to be stored within the Shopify structure through metafields. Metafields allow Shopify users to store custom information within a product and Cylindo users need a couple of custom fields, per product and per variant, to store the Cylindo codes on the customer's website.

 

Once the Cylindo codes exist in a product, Shopify can recognize them and send them through the Viewer API to generate a 360 HD Viewer instance. Please refer to this documentation if you would like more information on the purpose of metafields.

 

Since version 2.0 of the Online Store, Shopify has introduced multiple improvements for metafields and now they can be controlled through Shopify without Apps, APIs or code. This video shows how to create metafields.

 

It is also important to mention that Shopify variants and options are limited so Shopify users needs to make sure that the products do not fall outside the limits established in the official documentation.

 

The purpose of the third party applications mentioned in the above documentation is to increase and customize the fields of the forms that Shopify enables for the products and variations. So if a Shopify user finds that some of the products in the website will fall outside the limits this is something that the development team should fix before continuing with this example.

The below applications are some examples of the above tools:

• Bold Product Options
• Infinite Options

Please notice that some of the apps provided by Shopify are free and some others require payment. For the paid applications our suggestion is to look for the apps with a free trial just in case it does not cover your expectations.

 

The rest of the implementation requires some effort to enable the 360 viewer in the product detail view instead of the default Shopify viewer.

1. Prepare a product and its variants.

For this example, we’ve created in Shopify a product named ARMCHAIR.

This new product has 2 features, Fabric and Wood colors. Each of these features have 2 options, for the Fabric color we’ve enabled the Cow hide white/black and the White leather options while for the Wood finish we’ve enabled Beechwood 1 and Beechwood 2. It results in 4 possible variants so the resultant product form should look like this:

Options set for the ARMCHAIR product:

Default configuration of the ARMCHAIR product.

2. Create the metafield definitions for the product and its variants.

• In the main menu of the admin panel of Shopify, click on the Settings and then click on metafields in the new menu displayed.

• In the new panel displayed there is a menu with 2 options at the beginning of the list, Products and Variants. These 2 options will allow us to create the metafield definitions needed in the Product and Variant levels, in the product level we need to store the Product Code while the Variant level will store the features needed for that specific combination of the product. So, we first need to define these metafields.

• Click on Products, then click on Add definition and fill the form with the below information.

• We’ve filled in the Name of the metafield, the namespace and the metafield key, and the metafield description, for the Product code. Please also notice that the type of the metafield has been set to Single Line Text.
• In case you need it you can also set the Maximum and the minimum sizes for the metafield, but they’re not mandatory for the Cylindo implementation.
• Once they’re ready and you clicked Save, the metafield should look like this:

• Now we need to create a metafield in the product level to store the features, but now we need to go back to Metafields, and click on Variants, then click on Add definition and fill the form with the below information.

• We’ve filled in the Name of the metafield, the namespace and the metafield key, and the metafield description, for the array of features needed by Cylindo for each variant. Please also notice that the type of the metafield has been set to Single Line Text.
• Once they’re ready and you clicked Save, the metafield should look like this:

• When both definitions are ready, we can proceed to add the metafields for each product.
• To add the metafields, we need to open the Products module from the main menu of the admin panel, and we need to scroll down until we see the product metafields. In the form displayed, we need to add the Cylindo Product Code.

• When the Product code is set, we need to click on Save.

• Now scroll up to the Variations section and click Edit to modify the first variation.

• In the Variation, scroll down until the Metafields section and fill the input with the array of features that corresponds to the variation.
• For the first variation, the feature metafield should look like this: ["FABRIC_MATERIAL", "COW HIDE BLACK/WHITE", "WOOD_MATERIAL", "BEECHWOOD 1"]
• Repeat the process for the rest of the variations.

When the environment is set, now we just need to modify the default Shopify’s viewer and display the Cylindo 360 viewer. For it we need to follow the next steps.

IMPORTANT: Please notice that this example has been created using the default theme of Shopify named Debut, so some HTML elements or CSS selectors may be different.

1. Adding viewer.min.css and viewer.min.js

The first step to implementing the 360 HD Viewer is adding the Viewer files to your theme. Locate the theme.liquid file in the theme editor. Start by adding the viewer.min.css and the viewer.min.js files before the </head> tag.

2. Add the HD 360 Viewer element in the product-template file

The next step is to add the HD 360 Viewer element next to the Default Viewer element. Locate the product-detail.liquid file and append the element.

For this example, we’re also adding and id for the default viewer element, and also the display: none; css attribute to both elements, this is needed to keep both elements hidden when the DOM is loaded, then when one of the 2 viewers is loaded, we’ll remove that property and display the required viewer.

3. Append the below script tag at the bottom of the page.

The complete source code for the script tag and its explanation can be found here: https://codepen.io/cylindo/pen/NWjpomv

The below list explains how the above code works to get the viewer instance loaded in your PDP:

• Everything is loaded after the document is ready. To detect the event, it uses the ready event triggered from the document object.
• After that, it gets the 3 HTML elements needed to handle the DOM using jQuery. These elements are: #ProductSelect-product-template, #cylindo-viewer and #default-viewer.
  • The first element stores the ID of the current variation displayed in the PDP. It has the value since PDP is loaded and it gets modified when the variation is changed through the configuration panel.
  • The other 2 HTML elements are used to show the viewer.
• The next piece of code is getting the metafields that we’ve stored in the back-end from the global namespace.
• The following variables are declared and defined using the metafields, please notice that we’ve also set the account ID as a metafield in the product level, this is not necessary and it could be a static value set directly in the PDP.
• If all the required values to create the viewer instance are defined, we can continue creating the viewer instance.
• After the creation of the viewer instance the next step is to subscribe to the configuration panel events to detect any change. When the variation is changed, we search into the variations array the id of the new variation set and we use the features array of the new variant to execute the setFeatures method.

4. Result

Once the product and configuration are set, the next step is to review our demo page: