Shopify App user guide

This user guide explains how to get started with the Cloudinary app for Shopify. You will learn how to upload your product media from Shopify to Cloudinary, add media from Cloudinary into your themes, and start seeing the benefits of optimized, responsive and customized media on your storefront.

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, 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.

See also the Shopify app video tutorial.

Installation

The official Cloudinary integration for Shopify is available as a Shopify custom app that can be installed in your Shopify store. Enabling the app for your store requires help from our support team.

Create a support request for help installing and enabling the app in your store.

Pre-requisites

These instructions assume that:

  • You have a Cloudinary Programmable Media account. If you don't have one yet, you can quickly register for free.
  • You already have a store set up in Shopify. If you don't, you should do that first.
  • You have the Cloudinary app installed in Shopify.
  • You have linked the app to your Cloudinary account. If not:
    1. In Shopify, open the Cloudinary app from the Apps menu item.
    2. Click Connect to Cloudinary to log into your Cloudinary account.

Upload your Shopify product media to Cloudinary

To unleash the power of the images and videos on your storefront, you must first upload your product media to your Cloudinary account.

Run these steps to upload your Shopify product media to Cloudinary, both when you're getting started and also when you add new product media to Shopify:

  1. In Shopify, open the Cloudinary app from the Apps menu item.
  2. (First time only:) 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. If the path doesn't exist in Cloudinary, it will be created when media is uploaded. Once set, you cannot change this.

    Sync media
  3. Click Start Media Upload to start uploading your product images and videos from Shopify to Cloudinary. This process may take some time.

    Caution
    Do not update any product assets in Shopify while the upload is in progress.

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.

As part of the sync feature, tags and metadata are set on the assets in Cloudinary, and metafields are populated in Shopify. For details, see Appendix A - tags, metadata and metafields.

Tips

  • Remember to use this sync feature each time you add new product media to Shopify or change an existing product's media. Only new or modified assets are uploaded to Cloudinary (this includes changes to metadata such as the alt text, tags or position).
  • Videos that you have associated with your product via links, for example to YouTube or Vimeo, are not synced to Cloudinary. You can manually upload these videos to Cloudinary, then use Cloudinary Media Manager to associate them with products in Shopify.

Display images and videos on your site

Whether you're using an Online Store 2.0 theme or a vintage theme, you can add Cloudinary images and videos to your site by editing your theme's code.

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

Cloudinary liquid snippets

  • cloudinary-image-tag.liquid: Builds an image tag with multiple sources to render product images on your site lazily, applying transformations, and with appropriate responsive breakpoints set.
  • 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: Uses cloudinary-image-tag or cloudinary-video-tag to render product images or videos on your site, with optional transformations, and 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 transformations that you want to apply.
  • cloudinary-video-tag.liquid: Renders a video on your site, applying transformations, either using the video player, if enabled, or by building a video tag.

You can use these snippets in your theme's code, referencing them in other snippets or sections.

Add Cloudinary Liquid snippets to a new theme

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 Get Latest Snippets in the Settings page of the app.

Update active theme

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. Avoid duplicating images and videos on your page by removing any code from your current theme that already displays them on the page.
  2. Assign the productmedia JSON from the metafields to a local variable:

    Copy to clipboard
    {%- assign cld_media = product.metafields.cloudinary.productmedia_v1.value -%}
  3. 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

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.

    Cloudinary theme settings

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. Avoid duplicating images and videos on your page by removing any code from your current theme that already displays them on the page.
  2. Assign the productmedia JSON from the metafields to a local variable:

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

    Copy to clipboard
    {%- assign main_url = product.metafields.cloudinary.primaryimage_v1 -%}
  4. 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


You also need to enable responsive functionality, as follows:

  1. In the theme.liquid file, in the <head> section, add this line of code:

    Copy to clipboard
    <script src="{{ 'lazysizes.min.js' | asset_url }}" async="async"></script>

Changes required in theme.liquid to enable responsiveness

See also: Apply transformations to product media.

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.

You can apply Cloudinary transformations to optimize your media, add overlays, apply visual enhancements and more, by passing the necessary URL syntax in the transformations parameter.

For example, to optimize for quality (q_auto) and format (f_auto):

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

Apply transformations to product media

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

You can apply additional Cloudinary transformations to enhance your media, add overlays, apply visual enhancements and more, by passing the necessary URL syntax to the cloudinary-product-media.liquid snippet (in the image_transformations and video_transformations parameters).

For example, to round the corners (r_100) and apply an effect to improve the appearance of images (e_improve), and remove audio from videos (ac_none):

Copy to clipboard
{%- render 'cloudinary-product-media', cld_media: media, image_transformations: 'r_100/e_improve', video_transformations: 'ac_none' -%}

Make product images responsive

A default set of responsive breakpoints is 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.

You can change the set of breakpoints by editing the image_sizes variable in the snippet.

Cloudinary theme settings

Note
Assets delivered through the Product Gallery are automatically responsive, as are videos played using the Cloudinary Video Player.

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.

    Cloudinary theme settings

    Note
    The Cloudinary app supports the Video Player version 1.09 and above.

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.

Change your Cloudinary domain

Cloudinary allows you to set up a private CDN or CNAME to replace the default Cloudinary domain used for asset delivery URLs.

You can see the domain that the Cloudinary Shopify app believes to be configured for your Cloudinary account in the Cloudinary app settings. If you change the Cloudinary domain after you've logged into the app, you need to update the app by clicking the Update Domain button in the Cloudinary Domain section of the app settings.

Update Cloudinary Domain setting

Manage product media

There are two different ways to manage your product media with the Cloudinary app for Shopify. You can choose to either:

Continue with Shopify as the source of product media

If you don't want to use Cloudinary as the source of your media, you can continue to add media to your products in Shopify in the usual way. You need to remember to use the sync functionality after adding or making changes to your product media.

Make Cloudinary the source of product media

Initially, you need to migrate your Shopify product media to Cloudinary, as explained in Uploaded your Shopify product media to Cloudinary.

Following this, you can choose to make Cloudinary the source of product media, by storing all your assets in your Cloudinary Media Library, and adding them to Shopify via the Cloudinary Media Manager.

You can access the Cloudinary Media Manager by selecting a product from the Products page, then clicking More actions > Cloudinary Media Manager.

Cloudinary Media Manager

Click Add Media to open the Cloudinary Media Library. You can then search for and select the media you want to insert. If the media is not already in your Media Library, you can upload it to Cloudinary from here too.

The Cloudinary Media Manager shows any media that you uploaded to Cloudinary during the initial migration, in addition to media added directly from Cloudinary.

You can use the Cloudinary Media Manager to preview the media, update the alt text for each item, as well as delete media that you no longer require.

You can also rearrange the order of media here, which determines the order of media shown in the Product Gallery.

Notes

  • Media deleted from Shopify is not automatically deleted from the Cloudinary Media Library.
  • You can only delete media that you've added from Cloudinary. If media was originally added within Shopify, you cannot delete it here.
  • If you make any changes to the media in Cloudinary, these changes will be reflected in your Shopify media and may result in Shopify media being overwritten.
  • Images inserted through the Cloudinary Media Library are also uploaded to Shopify, however videos are not. For both images and videos, references are maintained in the Shopify metafields.
  • The order of media in the product management page may not reflect the order of media in the Cloudinary Media Manager.
  • If you do happen to add media to your products through the usual Shopify interface, then you need to remember to use the sync functionality.

Commonly-used Media Library features

When you click Add Media to open the Cloudinary Media Library, you may be asked to log into your Cloudinary account. You can access almost all of the same functionality that is available in the full Media Library in your account console.

Note
The Safari browser may require additional steps when logging in to the Media Library. If you encounter an issue, follow the prompts to log in separately and attempt to open the Media Library again. Alternatively, use one of the other recommended browsers when working with Cloudinary.

Advanced Search

The Advanced Search feature lets you search by filters such as tags, metadata, format, orientation, resolution, or (if supported for your account), even by image analysis characteristics, such as prominent colors, presence of faces, or image location.

Advanced Search

For more details, see Advanced Search in the Digital Asset Management guide.

Collections

Collections are ad-hoc groupings of assets. Assets can be added to and from collections without affecting or moving the asset itself, and assets can be included in multiple collections. You can create your own collections (assuming you have the required permissions) or other Cloudinary users can share collections with you. You can also share collections with external stakeholders by sending a URL to a dedicated collection webpage, which is available to those with a link during an optionally specified date range.

Collections can often be a convenient way to group all assets that you might want to use on a particular project or campaign.

Media Library collections

For more details, see Collection management in the Digital Asset Management guide.

Tagging and metadata

Assets that have tags and other metadata enable all Media Library users to better organize and search for assets in the Media Library.

In addition to the option to specify tags when you upload an image or video, you can also add or edit tags and other metadata after images and videos are uploaded via the embedded Media Library, and even set the same tags or metadata on multiple images and videos at once.

You can view and set this data using the Asset toolbar or in the Asset management page.

Asset toolbar

You can set tags and metadata for several selected assets at once from the main Media Library view using the Tag or Edit Metadata options in the asset toolbar. The type of metadata available for editing (contextual or structured) depends on the settings for your organization's account.

Media library asset toolbar

Asset management page

You can view or edit tags and metadata as well as view embedded image metadata for a specific asset from the Summary and Metadata tabs of the Asset management page.

To open the Asset management page either double-click the asset or select Manage from the asset's context (right-click) menu.

Asset management

Tip
From the Asset management page, you can also select a pre-defined transformation of the original asset (a 'Transformation Preset'), view or activate a variety of image analysis options in the Analysis tab, and more. For details, see Asset management drill-down in the Digital Asset Management Guide.

Media Editor

The Media Editor is only applicable to images and is accessible from the Asset management page, by clicking the Edit Image button.

In the Media Editor, you can crop and resize your image to suit your design. If you save the modified image, your current asset will be overwritten. You can retrieve the original if you have backups enabled. Otherwise, you may prefer to download the modified image and upload it as a new asset.

Media library media editor

Transformation editor

The transformation editor is accessible from the Asset management page, by clicking the Transform button.

In the transformation editor you can apply, and preview various transformations, then click Insert to use this transformed asset as your media item. Unlike when using the Media Editor, your original asset remains unmodified.

Media library transformation editor

For more details, see Asset and transformation editing in the Digital Asset Management guide.

Uninstall the Cloudinary app for Shopify

When you uninstall the Cloudinary app for Shopify, note that:

  • The Cloudinary snippets added to your theme's code are not removed. If you are not referencing these snippets in your code then you can delete these snippets manually.
  • You may want to clean up your metadata and tags in Cloudinary if you plan to reinstall the app at a later date.
  • On uninstall, all metafields in the cloudinary namespace are deleted. This may impact any other apps that also happen to use the same namespace.

Appendix A - tags, metadata and metafields

As part of the sync feature, and when adding media through the Cloudinary Media Manager, 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 or added to a product using the Cloudinary Media Manager:

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.

Metadata

The following structured metadata fields are automatically created and populated for the assets in Cloudinary that are uploaded from Shopify or added to a product using the Cloudinary Media Manager:

Metadata field Type Value Description
Image alt text 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.
Is image synced Boolean True or false. States whether or not the image has been synced to 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 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 or added to a product using the Cloudinary Media Manager.

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 assets associated to a product. For example, the Public ID and position. 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.

✔️ Feedback sent!

Rate this page: