Salesforce Commerce Cloud Site Cartridge FAQ

Here are some frequently asked questions about Cloudinary's Salesforce Commerce Cloud site cartridge. If you need help with a question not covered here, try the Knowledge Base or contact our support team.


How do I install the site cartridge?

Depending on the SFCC reference architecture that you're using, see:

Following installation, you need to make code changes to the templates to enable all of Cloudinary's functionality in your site. For reference, we provide cartridges that contain the necessary code changes for SFCC's demo site, which you can use as a guide.

Learn more: Cloudinary SiteGenesis LINK Documentation | Cloudinary SFRA LINK Documentation


How do I map my product assets in SFCC to my images and videos in Cloudinary?

There are two ways to map your SFCC product assets to your media in Cloudinary.

  • With Option 1, assets in Cloudinary are mapped to products in SFCC using tags and structured metadata. There are jobs you can use to do a one time migration of assets from SFCC to Cloudinary. These jobs add the necessary product tags and metadata to assets to get you started.
  • With Option 2, assets are expected to reside in Cloudinary using paths of the form: <prefix_path>/images/<path_in_sfcc>

    Where:

    • <prefix_path> is defined by the custom preferences in Cloudinary Core Configurations:
      • Folder For Product Images In Cloudinary, for images
      • Folder For Product Videos In Cloudinary, for videos
    • <path_in_sfcc> is the path used for the asset in SFCC.

    With this option you need to run jobs periodically to upload assets from SFCC to Cloudinary. The jobs also add tags and metadata automatically to the assets, which can help with searching within the DAM and are required if you migrate to Option 1.

Learn more: Media mapping options


How does the site cartridge decide which asset to use in the product listing page (PLP)?

You may have many assets associated with one product, but in the PLP, you only want one asset to be displayed. The site cartridge chooses the asset set for the master variant of the product that has the sfcc-is-main metadata set to true. Additionally, for each of the product variants, one of the assets must have sfcc-is-main set to true, so that when the customer selects a certain swatch, the matching variant's main asset is displayed.

Notes

  • If you have multiple assets with sfcc-is-main set to true, the first asset returned in the Cloudinary API response is used in the PLP.
  • When you change the structured metadata value for assets, it can take some time for the Cloudinary caches to update and for the changes to appear on the site.

Learn more: Example images showing tags and structured metadata


How do I use Cloudinary's Product Gallery?

  1. Enable Cloudinary's Product Gallery in product details pages (PDPs):

    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 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:
    Copy to clipboard
    {
            "container": "#cld-gallery",
            "displayProps": {
                "mode": "classic",
                "columns": 2,
                "spacing": 15
            },
            "aspectRatio": "3:4",
            "transformation": {
                "crop": "fill",
                "background": "#FFFFFF"
            },
            "bgColor": "transparent",
            "carouselLocation": "left",
            "carouselOffset": 10,
            "navigation": "always",
            "thumbnailProps": {
                "mediaSymbolSize": 42,
                "spacing": 20,
                "width": 90,
                "height": 90,
                "navigationFloat": true,
                "navigationShape": "square",
                "navigationSize": 40,
                "navigationColor": "#ffffff",
                "selectedStyle": "border",
                "selectedBorderPosition": "bottom",
                "selectedBorderWidth": 4
            },
            "navigationButtonProps": {
                "shape": "rectangle",
                "iconColor": "#ffffff",
                "color": "#000",
                "size": 52,
                "navigationPosition": "offset",
                "navigationOffset": 12
            },
            "themeProps": {
                "primary": "#000000",
                "active": "#777777"
            },
            "accessibilityProps": {
                "mediaAltSource": "metadata",
                "mediaAltId": "sfcc-alt-text"
            },
            "sortProps": {
                "source": "metadata",
                "id": "sfcc-gallery-position",
                "direction": "asc"
            }
        }
  2. Order the assets in the Product Gallery by setting the sfcc-gallery-position metadata for each product asset in Cloudinary to the required position number.

    Note
    The sortProps property in the JSON determines how the assets are ordered in the Product Gallery.

  3. Set the alt text for each asset in the sfcc-alt-text structured metadata field for each product asset in Cloudinary.

    Note
    The accessibilityProps property in the JSON determines which field to use in the alt text.

  4. Set which images and videos are displayed in the Product Gallery for each product by tagging the assets with the same tag: <master-product-tagname>-<variation-color-value-id>, where <master-product-tagname> is the unique product identifier, and <variation-color-value-id> is the color ID of the variation.

Learn more: Product Gallery Guide | Product Gallery Reference


How do I display videos on my site?

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

Note
If you have both the Product Gallery and the Video Player enabled, the video displays twice on the page.

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:

    Copy to clipboard
    {
        "fluid": true,
        "controls": true,
        "fontFace": "Lobster",
        "colors": {
            "base": "#de1e1e",
            "accent": "#180cff",
            "text": "#222121"
        }
    }

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 choose to store your videos in Cloudinary, or 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 How do I map my product assets in SFCC to my images and videos in Cloudinary? (Option 2).

Videos stored in Cloudinary only

Enable videos as follows:

  1. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Asset Management Configurations.
  2. Set Cloudinary Videos Enabled to Yes.
  3. Set Cloudinary Use Video Custom Mapping to Yes.
  4. Set Cloudinary Video Custom Map Path to the path to your videos.
  5. Set Cloudinary Custom Mapping Video Format to the format you want to use for videos.
  6. Ensure that your videos stored in Cloudinary have public IDs that follow the naming convention specified in Cloudinary Video Custom Map Path.
Videos stored in SFCC and copied to Cloudinary

Enable videos as follows:

  1. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Asset Management Configurations.
  2. Set Cloudinary Videos Enabled to Yes.
  3. Set Cloudinary Include Videos By View Type In PGW to Yes to include videos in the Product Gallery.

Learn more: Product Gallery | Video Player


Why is my video either not displaying, or showing twice in a product details page (PDP)?

Cloudinary's Product Gallery displays all assets (images and videos) that have the same tag. So, to include a video in your Product Gallery ensure that it has a tag of the form <master-product-tagname>-<variation-color-value-id>, where <master-product-tagname> is the unique product identifier, and <variation-color-value-id> is the color ID of the variation. If the video is set for the master variant of the product then it should also have <master-product-tagname> as a separate tag.

If Cloudinary's video player is enabled, any videos tagged for the product are displayed in the PDP. Therefore, if you are using the Product Gallery and have the video player enabled, you will see the video both in the gallery and displayed separately on the page. If this is not desired, and you only want it to be displayed in the Product Gallery, ensure you disable the video player by going to Merchant Tools > Custom Preferences > Cloudinary Asset Management Configurations and set Use Cloudinary Video Player to No​.

Note
If you disable the video player, you may be disabling videos elsewhere on your site too, depending on how your site is set up. For help with custom configurations, contact our support team.

Learn more: Product Gallery | Video Player


How do I make my images and videos responsive?

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 also 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:

    Copy to clipboard
    <iscomment> Custom Start: include cloudinary static libs. </iscomment>  
    <isinclude template="include/cloudinaryStaticLibs"/>  
    <iscomment> Custom End: include cloudinary static libs. </iscomment>
  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 on a per page type basis. For example, to make images on product listing pages responsive, use the following JSON structure:

    Copy to clipboard
    "plp": {
        "automateResponsivenessWithJS": true,
        "autoResponsiveDimensions": "w_auto,c_scale",
        "dimensions": "w_250",
        "breakpoints": {
            "size200w": {
                "style": "(max-width: 480px) 200px",
                "width": "200",
                "height": "300"
            },
            "size113w": {
                "style": "(max-width: 768px) 113px",
                "width": "200",
                "height": "150"
            }
        }
    }

    Use these page types to make images responsive on different pages:

    • pdp: product details page
    • plp: product tiles on the product listing page
    • searchSuggestions: suggested products under the search bar
    • cldPlpSwatch: swatch images on the product listing page
    • cart: product cards on the cart page
    • quickview: quick view modal
    • miniCart: mini cart drop down
    • checkout: all parts of the checkout page including shipping, billing and placing an order
    • orderConfirmation: order confirmation page

There are two ways to achieve responsiveness:

  • Generate HTML srcset and sizes attributes for <img> tags:
    • Set "automateResponsivenessWithJS" to false
    • Include "dimensions" and "breakpoints" (see above)
  • Use Cloudinary client side libraries:
    • Set "automateResponsivenessWithJS" to true
    • Include "autoResponsiveDimensions" (see above)

Learn more: Responsive images


Why are my lazy loaded images not responsive?

Images are made responsive through the function call, makeCloudinaryImagesResponsive(). This is called on page load from int_cloudinary/cartridge/js/cloudinaryWidgets.js. Images that are lazy loaded are requested after this call has been made, so they are not made responsive. In order to make them responsive you need to call makeCloudinaryImagesResponsive() after they have loaded.

Learn more: Lazy loading


How do I set alt text on images?

Alt text for images in Cloudinary's Product Gallery is configured as described in How do I use Cloudinary's Product Gallery.

For other pages, the alt text depends on which option you are using.

  • For Option 1, the alt text specified in the sfcc-alt-text structured metadata field is used, provided that the Add alt text in all images custom preference is enabled.
  • For Option 2, the alt text specified in SFCC for the view type is used.

Learn more: Setting structured metadata values


How do I manage tags and structured metadata for products?

As described in Tags and structured metadata, if using Option 1, assets in Cloudinary need to have certain tags and metadata applied.

You can apply tags by managing individual media assets or through bulk updates.

You can set structured metadata values for assets individually. To update the structured metadata values of many assets at the same time, contact support, who can guide you through the process of creating a CSV file containing a list of your Cloudinary assets and the metadata values to apply, to use for a bulk update.

Learn more: Managing individual media assets


How do I set a custom hostname?

If you have a private CDN or CNAME set up for your Cloudinary account, you need to set this in SFCC, as follows:

  1. In Business Manager, select your site, then navigate to Merchant Tools > Site Preferences > Custom Preferences > Cloudinary Core Configurations.
  2. Set Cloudinary Base Delivery Path to the base path, for example https://<custom domain name> or https://<cloud_name>-res.cloudinary.com.

If you are looking to set up a private CDN or CNAME for your Cloudinary account, contact support.

Learn more: Private CDNs and CNAMEs

✔️ Feedback sent!

Rate this page: