Skip to main content

Shopify integration

Introduction

The purpose of this guide is to integrate the Cylindo Viewer into a Shopify online store.

In most cases, this integration should be as straightforward as adding a few scripts. However, depending on how your Shopify and Cylindo projects are configured, additional steps might be needed.

Pre-Requisites

  • A Shopify online store running a Shopify Online Store 2.0 theme. This guide should work on other themes, but some adjustments might be necessary.
  • A Cylindo Customer ID
  • Configured Cylindo products matching every store product
  • Familiarity with Shopify's Admin Interface

Edit the Shopify theme code

First, go on your Shopify admin dashboard. Make sure you select the store where you plan to integrate the viewer.

Select your online store on the left panel:

Online store click

Click on the current theme's menu button, and select Edit code.

Edit code click

You'll then access an interface where you can edit every file of your store's current theme.

Add the imports to the theme

Search for the file theme.liquid, and open it. This file contains all the external scripts imports.

Locate the code {{ content_for_header }} in the file, and add the following block below:

  <link rel="preconnect" href="https://content.cylindo.com" crossorigin />
<script
type="module"
src="https://viewer-cdn.cylindo.com/v1/index.mjs"
async
></script>
<script
type="module"
src="https://viewer-cdn.cylindo.com/v1/shopify.mjs"
async
></script>

Click the Save button on the top right corner.

The whole code section should look like this:

Scripts import code result
info

If you want to include a Thumbnail bar, you should also add the following code to the copied block:

  <script
type="module"
src="https://viewer-cdn.cylindo.com/v1/bar.mjs"
async
></script>

Add the viewer to the theme

We will now locate the code responsible for displaying the product gallery, in order to replace it with the viewer.

Search for the file product-media-gallery.liquid, and open it.

caution

If your theme is not one of the 10 most popular Shopify themes, this file might not exist. In that case, look for a file named main-product.liquid, product.liquid or product-template.liquid. This file should contain the elements that will be displayed on your product page, including the gallery that you'll have to replace. If this doesn't help, please refer to your theme's documentation.

Replace the content of the whole file with the following code:

info

If you previously went through the old Shopify integration guide and have your cylindo_features and cylindo_product_code metafields configured and populated, please copy the code from the "Metafield method".

<cylindo-viewer
customer-id="YOUR CUSTOMER ID"
code="{{ product.handle }}"
>
<cylindo-shopify-integration
features-by-variant-id='{ {% for variant in product.variants %}"{{ variant.id }}": { {% for i in (0..product.options.size-1) %}{{ product.options[i] | json }}: {{ variant.options[i] | json }}{% unless forloop.last %},{% endunless %}{% endfor %} }{% unless forloop.last %},{% endunless %}{% endfor %} }'
default-variant-id="{{ product.selected_or_first_available_variant.id }}"
></cylindo-shopify-integration>
</cylindo-viewer>

Replace YOUR CUSTOMER ID by your own Cylindo Customer ID. The end result should look like this:

Viewer code end result

You can customize the viewer as you want, by copying one of the documentation examples. Here's a few relevant implementation examples:

This example follows the Preloading best practice. This improve loading times and SEO.

Don't forget to replace YOUR CUSTOMER ID by your own value.

<cylindo-viewer>
<img
slot="placeholder"
src="http://content-v2.cylindo.com/api/v2/YOUR CUSTOMER ID/products/{{ product.handle }}/default.webp"
/>
<cylindo-shopify-integration
features-by-variant-id='{ {% for variant in product.variants %}"{{ variant.id }}": { {% for i in (0..product.options.size-1) %}{{ product.options[i] | json }}: {{ variant.options[i] | json }}{% unless forloop.last %},{% endunless %}{% endfor %} }{% unless forloop.last %},{% endunless %}{% endfor %} }'
default-variant-id="{{ product.selected_or_first_available_variant.id }}"
></cylindo-shopify-integration>
</cylindo-viewer>

Click on the Save button, and then on the Preview store button located right above. You should now see a preview of your store.

info

If you want to go back to a previous version of your theme, you can do so by selecting it under the Recent changes section:

Revert recent changes

Conclusion

Verify that the viewer operates correctly and without issues across all products. If no problem is to be reported, your theme is now ready to be published.

Troubleshooting

If an error message appeared in place of the viewer, additional steps are required:

Error: Could not retrieve product

Please follow this additional guide if you got an error message similar to this one:

Wrong product code error message

Error: A feature with the specified code does not exist

Please follow this additional guide if you got an error message similar to this one:

Wrong feature error message