Developer guide

This page explains how to configure and incorporate advanced Cloudinary components in your app, such as the Product Gallery and videos delivered from Cloudinary, using Cloudinary's Video Player and within the Product Gallery. In addition, you'll learn how to apply transformations, deliver responsive images and videos and manage non-product assets within your SFCC B2C Commerce environment.

In the Code changes subpage, detailed information is provided on the code modifications required to integrate Cloudinary into your Storefront application code.

Product Gallery configuration

Cloudinary's Product Gallery is an interactive user interface for displaying products on your site. It supports images, videos, 360 spin sets and 3D images.

Enabling Cloudinary's Product Gallery in product details pages

To enable the Product Gallery for product detail pages:

1. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Asset Management Configurations.
2. Set Use Cloudinary Gallery On PDPs to Yes.
3. Set Enable 360 SpinSets to Yes to display 360 spin sets.
4. Set Enable 3D Objects and use 3D Assets to Yes to display 3D images.

5. Set Cloudinary Gallery Look And Feel to the required JSON configuration settings. Use the Product Gallery Demo to customize the gallery, and copy the JSON from the Code tab. Remove the "cloudName" and "mediaAssets" properties as these are injected programmatically elsewhere. For example:

Note:

• You can set other configuration parameters in this JSON, as described in Initialize the Product Gallery widget. For example, to set a CNAME, set secure and privateCdn to true and secureDistribution to your custom domain name:

• The queryParam property in the JSON is set to AG by default and should not be changed. This query parameter is added to every asset URL in the Product Gallery and is used by Cloudinary for analytics.

Determining which assets are displayed in the Product Gallery

Tags are used to identify the assets in Cloudinary that are displayed in the Product Gallery on a particular product detail page.

All tags are based on the unique product identifier, shown as <master-product-tagname> in the table below.

Ordering assets in the Product Gallery

The sortProps property in the JSON (set in the Cloudinary Gallery Look And Feel custom preference) determines how the assets are ordered in the Product Gallery. For example:

In this case, you would order the assets in the Product Gallery by setting the sfcc-gallery-position structured metadata for each product asset in Cloudinary to the required position number. The assets would be displayed in ascending order according to the value set.

Setting alt text for assets in the Product Gallery

The accessibilityProps property in the JSON (set in the Cloudinary Gallery Look And Feel custom preference) determines which field to use in the alt text. For example:

In this case, you would set the alt text in the sfcc-alt-text structured metadata field for each product asset in Cloudinary.

Displaying videos

You can display videos on your product details pages (PDPs) using the Cloudinary Product Gallery. Additionally, you can display videos separately using the Cloudinary Video Player, or via standard HTML video tags.

In addition to displaying videos on PDPs, you can configure videos to display on other page types too through code customizations.

Displaying videos using the Video Player

To enable the Cloudinary Video Player:

1. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Asset Management Configurations.
2. Set Use Cloudinary Video Player to Yes.

3. Set Cloudinary Video Player Look And Feel to the required JSON configuration settings. Use the Video Player Studio to customize the player, and copy the JSON style settings from the Javascript tab, for example:

Displaying videos in the Product Gallery

The configuration required to display videos in the Product Gallery depends on the media mapping option you are using.

Option 1

If you are using Option 1, videos are enabled by default and will display in the Product Gallery provided they have the correct tags and metadata.

Option 2

If you are using Option 2 you can set up a custom view type for videos in SFCC and upload your videos to SFCC. These are then copied to Cloudinary as explained in Option 2.

Videos stored in SFCC and copied to Cloudinary

Enable videos as follows:

1. Set up a custom view type called video:
   1. In Business Manager, navigate to Merchant Tools > Products and Catalogs > Catalogs > (Your Catalog) > Image Settings.
   2. Click the Add View Type link to add a new view type with name, video.
2. Add a video to a product:
   1. Go to a product and click the Edit button to edit product images.
   2. For view type = "video", click the add icon to assign a video to the product.
   3. In the field, path, add the public ID of a video that exists in your Cloudinary product environment.
3. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Asset Management Configurations.
4. Set Use Cloudinary Gallery on PDPs to Yes.
5. Set Cloudinary Include Videos By View Type In PGW to Yes to include videos in the Product Gallery.

Videos stored in Cloudinary and accessed using custom mapping

The Cloudinary custom mapping option enables you to retrieve videos from Cloudinary and display them on the product detail page (PDP). This functionality utilizes Cloudinary as a single source of truth with path-based delivery, overriding cartridge operation mode settings for videos.

The retrieval process involves assigning a base path and defining additional tags to form the basis for a delivery URL that corresponds to the desired video to be showcased from Cloudinary.

To enable custom mapping for product videos in Cloudinary:

1. Enable the Cloudinary Video Player.
2. From Merchant Tools > Products and Catalogs > Catalogs > (Your Catalog) > Image Settings, set Cloudinary Videos Enabled to Yes.
3. Set Cloudinary Use Video Custom Mapping to Yes.
   • The base path defined in the Folder for Product Videos in Cloudinary section of Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Core Configurations serves as the foundation for video delivery URLs.
4. Use tags in the Cloudinary Video Custom Map Path section to determine the final URLs of the videos:
   • #locale#: The current locale of the site, e.g., en_US.
   • #sku#: The product ID.
   • #name#: The product name (without spaces).
   • #color#: The product's color attribute.
   • #size#: The size attribute of the product.
     
     

     Tags can be used individually or combined (e.g., #locale#/#sku#/#color#). Here, #local# and #sku# are folder names, and #color# will act as the name of the video configured in Cloudinary. Make sure the path aligns with the video's delivery URL in Cloudinary.

5. Enter the desired video format in Cloudinary Custom Mapping Video Format to be appended as an extension to the generated delivery URL.

Transformations

All Cloudinary image and video transformations can be applied at various levels in your store, with the transformations for the most specific level taking precedence. So, for example, a transformation that includes a text overlay showing 50% Off for an image on the product level will override a transformation with a text overlay saying 25% Off that was set for an image on the catalog level.

See these sections of the SFRA and SiteGenesis configuration pages to learn where you can specify transformations to apply to images at different levels.

• Configure the cartridge site preferences -> Cloudinary Transformation Configurations
• Configure custom attributes -> Catalog custom attributes
• Configure custom attributes -> Category custom attributes
• Configure custom attributes -> Product custom attributes
• Configure custom attributes -> Library custom attributes

Responsive images and videos

Any images and videos displayed with Cloudinary's Product Gallery are responsive by default, so they'll adapt to whatever viewing device your customer is using.

Likewise, videos displayed using Cloudinary's video player are responsive by default.

To make Cloudinary images outside of the Product Gallery responsive:

1. Open the file named htmlHead.isml and place the following code at the bottom of this file:

2. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Core Configurations.

3. In Cloudinary Image Page Type Settings, you can set up responsive images per page type.

Setting up responsiveness via the Cloudinary Image Page Type Settings

There are two ways to achieve responsiveness:

• Generate HTML srcset and sizes attributes for <img> tags:

  • This method builds on existing HTML-based responsiveness. In order for the cartridge to use srcset and sizes, your current implementation must incorporate them. Only after implementing HTML-based responsiveness, which is a separate scope, can you use the cartridge settings to support it.
  • This is the preferred option for less client-side code to impact Core Web Vitals.
  • Set "automateResponsivenessWithJS" to false.
  • Include "dimensions" and "breakpoints" to generate the required HTML attributes for the <img> tags (see above).
  • You can exclude "autoResponsiveDimensions" from the settings.
    
    For instance, if your PLP has a small screen layout with 2 columns and a large screen layout with 3 columns, you can specify that, for viewports up to 768px, images will automatically resize to 49% of the viewport, while for larger viewports, images will resize to 32% of the viewport.
    
    The following example demonstrates how to configure three different resolutions: 200px, 500px, and 900px. This is the JSON structure in the Cloudinary Image Page Type Settings:

• Use Cloudinary client-side libraries:

  • Set "automateResponsivenessWithJS" to true.
  • Include "autoResponsiveDimensions".
  • You can exclude "dimensions" and "breakpoints" from the settings.
    
    For example, to make images on product listing pages responsive using Cloudinary client-side libraries, enter the following JSON structure in the Cloudinary Image Page Type Settings:
    Note

    For more information, see Automating responsiveness with the cloudinary-core JS library.

JSON tips and considerations

• The dimensions parameter provides a fallback for user-agents that don't support srcset. (For debugging purposes, you can set an unusual number for the value of dimensions so that you can clearly see where the responsive breakpoint applied.)
• Make sure to follow the exact syntax as shown in the examples above.

Using hardcoded and custom page types

The following list includes all the page types that are hardcoded in both the SFRA and SiteGenesis cartridge's constants file. Add these page types to make images responsive on different pages:

• pdp: product details page
• plp: product tiles on the product listing page
• cldPdpSwatch: swatch images on the product details page
• cldPlpSwatch: swatch images on the product listing page
• searchSuggestions: suggested products under the search bar
• cart: product cards on the cart page
• miniCart: mini cart drop down
• checkout: all parts of the checkout page including shipping, billing and placing an order
• orderConfirmation: order confirmation page
• categoryBanner: category banner image
• cldhomePageProductTile: product tiles on the home page
• recommendationTile: recommendations tile on product details page.
• quickview: quick view modal
• cldProductNav: product navigation on product details page
• cldCartProductTile: last visited products tile on cart page

Besides the page types in this list, you can use any name that you'd like in order to set up custom page types. You may want to do that if you have several sized product or non-product assets on the same page. Just make sure you assign the desired page type to your assets on the SFCC backend.

Non-product assets

The following sections provide instructions for how to configure and customize non-product assets.

Load a Cloudinary image in a content asset

Open any content asset in which you want to load an image from Cloudinary, for example, open the about-us content asset, and add the following code to load a top hero banner background image from Cloudinary:

The query params are as follows:

• url: The relative URL of the image in Cloudinary. For Option 1, this is the path in the Media Library where the asset has been uploaded within the content folder (set in the Folder For Content Images In Cloudinary custom preference). For Option 2, this assumes that the Upload Content Assets job has been run to sync the asset into Cloudinary.
• pageType: The SFCC page type for this image.

• isURL: Set to true if a transformed URL is to be loaded, or false if an image tag with srcset and sizes attributes is to be loaded.

  • If the isURL parameter is set to false, you can utilize the attributes parameter to pass elements that will be included within the generated image tag:

    Here's the generated image tag:

Include the Cloudinary Video Player on a content page

Open any content asset in which you want to load a video from Cloudinary, for example, open the about-us content asset, and add the following code to load the Cloudinary Video Player:

The query param is:

• url: The relative URL of the video present in your static content library.