Shopify App (BETA)

Important
The Cloudinary Shopify app is currently in BETA. There may be minor changes to usage or other implementation details before the general access release. We invite you to sign up for the Shopify Beta program to try it out.

Overview

Shopify is an e-commerce platform that enables you to set up your own online shop. It offers a suite of services including payments, marketing, shipping and customer engagement tools to simplify the process of running an online store for merchants.

Key to online retail is having relevant images and videos portraying your products. By retrieving these from Cloudinary, you can maintain a single source of truth for all your assets, with all the DAM benefits that Cloudinary offers.

Additionally, you can easily optimize and customize your media on the fly using Cloudinary transformations, and deliver your media through fast content delivery networks.

Operational concepts

This animation shows how the Cloudinary app for Shopify operates at a high level:

Jump to this spot in the video  0:00 As a Shopify user, you create a product and upload your images and videos to that product in Shopify. You can add tags to the product and decide on the order of the images in Shopify to determine the main image for the product.
Jump to this spot in the video  0:07 The app gives you the ability to upload each of those media files to your Cloudinary Media Library with the push of a button. The assets in Cloudinary are tagged, and metadata fields are set, with information provided by Shopify, such as the product handle and tags set on the product.
Jump to this spot in the video  0:11 Cloudinary responds back to Shopify with information about the assets, such as their URLs, which is stored in product metafields in Shopify.
Jump to this spot in the video  0:13 The Cloudinary app Liquid snippets reference the metafields to display the images and videos on your Shopify store. You need to include these snippets in the appropriate places in your theme code. The media is delivered from Cloudinary in the most optimal way for the viewing device.

Get started

To get started with the Cloudinary Shopify app:

  1. Upload your Shopify media to Cloudinary.
  2. Edit your store's theme code, using the Cloudinary snippets to deliver media from Cloudinary.
  3. Inspect your store's media URLs to verify that images and videos are being delivered from Cloudinary.

Store media in your Cloudinary DAM

Maintain a single source of truth for your product media assets in your Cloudinary DAM by synchronizing media from Shopify to Cloudinary, and delivering all your media from Cloudinary. Manage your media in your Cloudinary DAM with the help of its asset management, search and sharing capabilities.

Upload Shopify Media to Cloudinary

The easiest way to upload your Shopify product media to Cloudinary is to use the sync feature in the app, as follows:

  1. In Shopify, open the Cloudinary app from the Apps menu item.
  2. If you don't yet have a Cloudinary account, click Sign up for Cloudinary and create a new Programmable Media Cloudinary account. Otherwise, click Connect to Cloudinary to log into your Cloudinary account.
  3. In the Sync to Cloudinary section of the Settings page, enter the folder path in Cloudinary to which you want to upload your media from Shopify. Once set, you cannot change this.
  4. Click Start Media Upload to start uploading the images and videos from Shopify to Cloudinary. This process may take some time.

Tip
Remember to use this sync feature each time you add new media to Shopify. Only new or modified assets are uploaded to Cloudinary (this includes changes to metadata such as the alt text, tags or position).

You can see the uploaded assets in your Cloudinary Media Library in the folder that you specified. For each product, a new folder is created, which contains the product assets.

Tags, metadata and metafields

As part of the sync feature, tags and metadata are set on the assets in Cloudinary, and metafields are populated in Shopify.

Tags

The following tags are automatically added to the assets in Cloudinary that are uploaded from Shopify:

Tag Description
The Shopify product handle. A unique product identifier that can be used for displaying assets in the Product Gallery.
The Shopify variant ID if applicable. The identifier of a product variant that can be used for displaying assets for variants in the Product Gallery.

Additionally, you can add any tags you like by specifying them in the TAGS field in the product page in Shopify. When assets are synced to Cloudinary these tags are also applied to the product assets in Cloudinary.

Note
Tags cannot be applied to individual images in Shopify, so any tags applied to a product in Shopify are applied to all of that product's images when uploaded to Cloudinary.

Structured metadata

The following structured metadata fields are automatically created and populated for the assets in Cloudinary that are uploaded from Shopify:

Structured metadata field Type Value Description
image_alt String The alt text for the asset as defined in Shopify. Used for alt-text in the gallery and wherever the image is displayed (e.g. product tile).
image_id Number The ID of the asset in Shopify. Can be used for searching in Cloudinary and other uses.
image_position Number The order of the asset in the Shopify product. Used to position the asset in the Product Gallery.
main_image Boolean True or false. States whether or not the image is the main image for the product in Shopify.
product_handle String The Shopify product handle. Can be used for searching in Cloudinary and other uses.
product_id String The unique GraphQL ID for the Shopify product. Can be used for searching in Cloudinary and other uses.
product_legacy_id Number The unique REST API ID for the Shopify product (legacy). Can be used for searching in Cloudinary and other uses.

Caution
The structured metadata fields are used internally by the app, so do not edit their values.

Metafields

The following metafield definitions are added to your products and product variants in Shopify when the Cloudinary app is installed on Shopify. They are populated when media is uploaded from Shopify to Cloudinary.

Metafield definition name Type Description
primaryimage_v1 String The URL of the primary image for the product in Cloudinary, including transformations. This is the image in position 1 in the product when the media is synced to Cloudinary.
productmedia_v1 JSON Information about the Cloudinary resources associated to a product. For example, the Public ID, position and breakpoints (used for responsive media). This information is returned from Cloudinary when media is synced to Cloudinary.
synced_v1 Boolean Shows whether the product media has been synced to Cloudinary.

Caution
The metafields are used internally by the app, so do not edit their values.

Display images and videos on your site

The Cloudinary app adds various Liquid snippets to your store's theme that provide the functionality to display images and videos on your site:

  • cloudinary-pgw.liquid: Renders the Product Gallery Widget on a page to display product images and videos in a customizable, responsive and accessible user interface.
  • cloudinary-product-media.liquid: If used for images, builds image tags to render product images on your site lazily, automatically optimized for quality and format, and with appropriate responsive breakpoints set. If used for videos, either builds video tags or uses the video player to render product videos on your site automatically optimized for quality and format.
  • cloudinary-url.liquid: Lets you build a Cloudinary URL to deliver an image or video on your site, from an asset's public ID and any transformation that you want to apply.
  • cloudinary-video-tag.liquid: Renders videos on your site, either using the video player, if enabled, or by building video tags.

These can be used in your theme's code, for example, in other snippets, or sections.

Add Cloudinary Liquid snippets to a new theme

When you install the Cloudinary app for the first time, the Cloudinary Liquid snippets are added to the theme that is currently active.

Cloudinary liquid snippets

If you change the theme that you're using for your store, and already have the Cloudinary app installed, you need to add the Cloudinary snippets into the active theme. You can do this by clicking Add Snippets in the Settings page of the app.

You can use the same mechanism to update the snippets to the latest code issued by Cloudinary.

Display media using the Cloudinary Product Gallery

Include images and videos on your product description pages using the highly customizable Cloudinary Product Gallery.

Cloudinary Product Gallery

To display the Product Gallery on a product page follow the steps below.

In the relevant Liquid template in your theme's code:

  1. Assign the productmedia JSON from the metafields to a local variable:

    Copy to clipboard
    {%- assign cld_media = product.metafields.cloudinary.productmedia_v1.value -%}
  2. Render the Product Gallery where you want it to appear on the page, using the cloudinary-pgw.liquid snippet and passing the local variable from step 1:

    Copy to clipboard
    {%- render 'cloudinary-pgw', media: cld_media -%}

Cloudinary Product Gallery snippet used in Shopify code

Note
If you're using the Cloudinary Product Gallery to display your media, then you'll probably want to remove any code from your current theme that already displays product images on the same pages.

Set the look and feel of the Product Gallery

To set the look and feel of the Product Gallery:

  1. Use the Product Gallery demo to customize the Product Gallery as required, then copy the JSON from the Code tab.
  2. In Shopify, go to your active theme and click Customize.
  3. Click Theme settings and scroll to the CLOUDINARY settings.
  4. In Product Gallery configurations, paste the copied JSON.

Display product media on a page

You can display product media on a page without using the gallery, by using the cloudinary-product-media.liquid snippet.

In the relevant Liquid template in your theme's code:

  1. Assign the productmedia JSON from the metafields to a local variable:

    Copy to clipboard
    {%- assign cld_media = product.metafields.cloudinary.productmedia_v1.value -%}
  2. Assign the primaryimage string from the metafields to a local variable:

    Copy to clipboard
    {%- assign main_url = product.metafields.cloudinary.primaryimage_v1 -%}
  3. You may want to iterate through the media items in your product media, in which case, set up a for loop to render all the media for a product:

    Copy to clipboard
    {%- for media in cld_media -%}
      ...
      {%- render 'cloudinary-product-media', cld_media: media, main_url: main_url -%}
      ...
    {%- endfor -%}

Cloudinary product media snippet used in Shopify code

Display any Cloudinary media on page

If you've got images or videos stored in Cloudinary that aren't part of a product, you can use the cloudinary-url.liquid snippet to build a URL that you can then use as the src attribute for an image or video tag in your templates.

For example:

Copy to clipboard
<img src="{%- render 'cloudinary-url', public_id: 'sample', type: 'image', transformations: 'q_auto,f_auto' -%}">

Transformations and optimizations

The default transformations added to product images by the cloudinary-product-media.liquid snippet are auto format and auto quality.

You can apply other Cloudinary transformations to enhance your media, add overlays, apply visual enhancements and more, by passing the necessary URL syntax to the cloudinary-url.liquid snippet.

For example, specifying auto quality (q_auto) and auto format (f_auto) together with rounding the corners of the image (r_100) and applying an effect to improve the appearance of the image (e_improve):

Copy to clipboard
<img src="{%- render 'cloudinary-url', public_id: 'sample', type: 'image', transformations: 'q_auto,f_auto/r_100/e_improve' -%}">

Responsive breakpoints

When images are uploaded to Cloudinary from Shopify, the best set of responsive breakpoints are calculated and stored in the productmedia metafield. These are then used by the cloudinary-product-media.liquid snippet to ensure that the optimal image size is delivered to each user based on the available space on their viewing device, be that mobile, desktop or other.

Display videos using Cloudinary's Video Player

Enable Cloudinary's customizable HTML5-based Video Player to display videos on your storefront in the way you want.

To enable and customize the Cloudinary Video Player on your site:

  1. In Shopify, go to your active theme and click Customize.
  2. Click Theme settings and scroll to the CLOUDINARY settings.
  3. Select the Use the Cloudinary Video Player for product videos checkbox.
  4. Use the Video Player Studio to customize the Video Player as required, then copy the JSON from the code box.
  5. Paste the JSON into Video Player configuration.
  6. You can also set the version of Video Player JavaScript and CSS that you want to use, but it is recommended to use the defaults.

If you do not enable the Video Player then videos are displayed using HTML video tags.

Verify that media is delivered from Cloudinary

You can inspect media URLs on your site using browser tools. For example, in Chrome:

  1. Right-click an image and select Inspect.
  2. In the panel that appears, click Network.
  3. Select the Filter icon and click Img.
  4. Reload the page, and see the images being requested.
  5. Click the name of an image to see the details:

    See details of a media URL request
    If the image is being delivered from Cloudinary, you will see:
    • The Request URL showing the Cloudinary delivery URL with the applied transformation (f_auto,q_auto,c_scale,w_800 in the above screen capture).
    • The content-type most likely being different from your original due to automatic format being applied (AVIF, rather than JPG in this case).
    • The server stating Cloudinary.

Guide to Building the Ultimate E-Commerce Website

 
You may also want to take a look at Cloudinary's five-chapter Guide to Building the Ultimate E-Commerce Website. The guide includes suggestions by e-commerce and technical experts on how to build a versatile marketplace by selecting automated e-commerce and CMS platforms that help you create, modify, and deploy adaptable user experiences.

✔️ Feedback sent!

Rate this page: