Salesforce Commerce Cloud B2C Commerce Cartridge operational overview

The Salesforce Commerce Cloud B2C Commerce cartridge enables you to simplify and automate the process of managing, transforming, optimizing, and delivering images and videos throughout your entire Commerce Cloud store, including product images and videos, 360 spin sets and 3D models, category assets, and site catalogs.

Media mapping options

Depending on your setup, there are three options for media mapping and delivery using Cloudinary:

Option 1 - media directly uploaded to Cloudinary (recommended)

• Cloudinary is the single source of all media for all catalogs, which gives you the benefits of the Cloudinary DAM to manage your assets.
• For the product catalog, assets in Cloudinary are mapped to products in SFCC using tags and structured metadata.
  Note

  For product variations, only images are supported, not videos. Both are supported for the master product.
• For the content and site catalogs, specify URLs to Cloudinary assets in content slots.
• If migrating from an existing site, you can run jobs to bulk upload your media to Cloudinary. Tags and structured metadata are automatically added to the assets in Cloudinary for the product catalog.
• You can use a Media Library app to update the structured metadata values of many assets at the same time. Contact support to guide you through the process of creating a CSV file containing a list of your Cloudinary assets and the metadata values to apply.
• You can use Cloudinary's Product Gallery for displaying product images, videos, 360 spin sets and 3D images.
• You can use Cloudinary's Video Player.
• Image paths and alt text can be stored in SFCC for use in product feeds and image tags, by running a specific job .

Option 2 - media uploaded to SFCC and copied to Cloudinary

• SFCC is the source of mapping for all media for all catalogs.

• For the product catalog, assets are also expected to reside in Cloudinary, but using the same paths as in SFCC, so that they are ultimately delivered from Cloudinary. The paths take 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.

• You need to run jobs periodically to upload and sync assets from SFCC to Cloudinary, and also to add tags and metadata to the assets automatically. Tags and metadata help with searching within the DAM and are required if you migrate to Option 1.

• For the content and site catalogs, specify URLs to Cloudinary assets in content slots.

• You can use Cloudinary's Product Gallery for displaying product images and videos.

• You can use Cloudinary's Video Player.

Option 3 - media fetched to Cloudinary on demand

• Media is automatically uploaded from its existing location to Cloudinary when requested by the end user, and is subsequently delivered from Cloudinary.
• This option is not recommended as it does not provide the same asset management benefits as the other two options, but exists to provide a quick and simple way to deliver your media from Cloudinary.

If you decided to implement your media mapping using one option, then at a later stage decide to use a different option, contact support to discuss migration paths.

Jobs

In SFCC, jobs are used to automate routine tasks or long-running processes. You can run them manually or schedule them to run at specific times.

The B2C Commerce cartridge contains the following jobs, which are primarily used for Option 2 - media uploaded to SFCC and copied to Cloudinary, but can also be used for Option 1 - media directly uploaded to Cloudinary if migrating from an existing site:

• Upload Product Assets

  • This job uploads all product assets (images and videos) from the product catalog into Cloudinary.
  • By default, the view type configured as the high-resolution source of images and swatch are uploaded, but you can also configure other view types to be uploaded.
  • Tags and structured metadata are applied to the uploaded assets.

• Upload Catalog Assets

  • This job uploads all catalog assets (images and videos) from the product catalog into Cloudinary.

• Upload Content Assets

  • This job uploads all content assets (images and videos) from the content catalog into Cloudinary.
  • If a content catalog is shared by multiple sites, you only need to run this job in the context of one of the sites to avoid unnecessary duplication of uploads from multiple job executions from multiple sites.

For each of the upload jobs, the root upload location in Cloudinary is specified in the custom preferences for the Cloudinary cartridge in SFCC, and the SFCC folder structure is automatically replicated in Cloudinary. You can use each of the jobs both to migrate all your SFCC media assets into Cloudinary and also subsequently to upload only new assets created in SFCC.

The cartridge also includes this job for Option 1:

• Import Image Path and Alt Text
  • This job is used to fetch public IDs and alt text from primary images in Cloudinary, which are then stored in SFCC to use for product feeds and image tags. See Importing Cloudinary delivery URLs for product feeds and Providing alt text for images for details.

Tags and structured metadata

If using Option 1 - media directly uploaded to Cloudinary, assets need to have particular tags and metadata based on the product catalog definitions in SFCC to identify all assets belonging to products and variants. These can be added directly into Cloudinary's DAM, as described below. When product images and videos are uploaded to Cloudinary using the Upload Product Assets job, the required tags and structured metadata are automatically assigned to them.

Assigning tags to product assets

There are three different tag types that can be assigned to assets:

• Product tag: This tag is the unique product identifier, which could be the product's ID, or some other unique identifier, such as UPC or SKU. Use the SFCC custom preference, CLDProductAttributeForTags, to indicate to the cartridge which attribute to use as the identifier. By default it is set to ID.
  
  In the example shown here, the tag name is 25721034M, same as the ID for the product:
  
  
  When displaying images and videos on a product page, the gallery automatically pulls in all assets with the same product tag.

  Note

  The Upload Product Assets job uses CLDProductAttributeForTags to assign the product tag automatically. Should you wish to override this global setting, you can specify the tag name itself on a per-product basis, using the Cloudinary Tag Name (CLDTagName) attribute (in the Cloudinary section of the product settings). Any assets in Cloudinary that have this tag will appear in that product's gallery.

• Variation product tag: This tag identifies particular variations of a product. In the example section below, there are two color variations of the product, Sundried Coral and Navy Sky. Each variation has its own set of images, so when the customer selects a color, the relevant images for that color are displayed in the gallery. The tag used for these product types takes 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.

  Note

  You can find the variant color IDs as follows:
  
  

  1. In Business Manager, open the product and click the Variations tab.
  2. In the Variation Attributes section, click the color attribute.
  3. See the values in the Defined Variation Values for color section.
     
     
  Important

  Only images are supported for product variations, not videos.
  

• Variation product swatch tag: This tag identifies the swatch image for a product variation. The tag used for swatch images takes the form: <master-product-tagname>-<variant-color-value-id>-swatch. Swatch images are used by the customer to select the color they want. The images displayed in the Product Gallery are based on the selected swatch.
  
  

Assigning structured metadata to product assets

The B2C Commerce cartridge requires you to define structured metadata fields in Cloudinary, as shown in the following table. You can then set the metadata on each asset to control, for example, where it's positioned in the Product Gallery and whether it's the main image for the product, etc. You can also use metadata in customized templates, for example, using the sfcc-gallery-position value to determine main and alternate images on mouseover.

Example images showing tags and structured metadata

The following table shows all the images stored in Cloudinary that are associated to the product with the unique identifier, 25721034M. Each has its own set of tags and structured metadata. Multiple images and videos that have the same tag are shown together in the same Product Gallery.

Image	Tags	Structured Metadata	Comment
	25721034M 25721034M-JJ9HWA0	sfcc-gallery-position: 1 sfcc-is-main: True sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: large	This is the main product image for this product variant, and is the master product, so it's shown on the product listing page.
	25721034M 25721034M-JJ9HWA0	sfcc-gallery-position: 2 sfcc-is-main: False sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: large	This is not the main product image for this product variant. It is shown second in the gallery.
	25721034M-JJC51A0	sfcc-gallery-position: 1 sfcc-is-main: True sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: large	This is a variation of the master product, so it doesn't have a master product tag.
	25721034M-JJC51A0	sfcc-gallery-position: 2 sfcc-is-main: False sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: large	This is a variation of the master product, so it doesn't have a master product tag. It's shown second in the gallery.
	25721034M-JJ9HWA0-swatch	sfcc-gallery-position: 1 sfcc-is-main: True sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: swatch	This is the Sundried Coral swatch image. JJ9HWA0 is the color ID for Sundried Coral.
	25721034M-JJC51A0-swatch	sfcc-gallery-position: 1 sfcc-is-main: True sfcc-product-identifier: 25721034M sfcc-product-name: Cut Away Tank sfcc-view-type: swatch	This is the Navy Sky swatch image. JJC51A0 is the color ID for Navy Sky.

On the product listing page you can see the master product image and both swatch images:

This is the product page, showing the Product Gallery, with the Navy Sky variation of the product selected:

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 to true and secure_distribution 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 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 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, this is the part of the URL that comes after the base path set in the Folder For Product Videos In Cloudinary custom preference. It can be composed using a combination of these tokens: #sku# (product id), #locale# (any locale), #name# (product name), #color# (the color ID) and #size# (the size ID). These tokens are replaced with actual values for the product to find the correct video. For example, if the path is /customVideos/#sku#/#color#.mp4, the video that is used will be <Cloudinary Base Delivery Path>/<Folder For Product Videos In Cloudinary>/customVideos/#sku#/#color#.mp4.
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. 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 Cloudinary Videos Enabled to Yes.
5. Set Cloudinary Include Videos By View Type In PGW to Yes to include videos in the Product Gallery.

Importing Cloudinary delivery URLs for product feeds

If using Option 1, all your media is stored in Cloudinary, so when creating product feeds from SFCC, you need to obtain information about the product images from Cloudinary.

The Import Image Path and Alt Text job gets the public IDs of all the product catalog primary images in Cloudinary and stores them in the 'large' view type for the product and variants in SFCC. This has the added benefit of being able to see product images in the Business Manager so you can easily see the product you're working with.

For each catalog, you can set an external URL for images as follows:

1. Navigate to Merchant Tools > Products and Catalogs > Catalogs > (Your Catalog) > Edit > Image Settings.
2. Set Image Location to External.
3. Set HTTP URL and HTTPS URL to the common part of your Cloudinary image delivery URLs, for example:
   https://res.cloudinary.com/mycloud/image/upload/f_auto/q_auto/,
   or https://www.example.com/image/upload/f_auto/q_auto/.
4. Click Apply to save the settings.

This allows the process that produces the product feed to construct the full image path using HTTPS URL + Public ID.

Providing alt text for images

Alt text for images in Cloudinary's Product Gallery is configured as described in Setting alt text for assets in the Product Gallery.

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

• For Option 1, the alt text that is specified in the sfcc-alt-text structured metadata field of the primary image in Cloudinary is used. The value of this field is imported into the CLD Alt Text For Images attribute in your product in SFCC when the Import Image Path and Alt Text job is run. This attribute can be inserted into the image tag used to display the image on your site.
  Note

  Currently the same alt text is used for each image in the product.
• For Option 2, the alt text specified in SFCC for the view type is used.

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

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:

There are two ways to achieve responsiveness:

• Generate HTML srcset and sizes attributes for <img> tags:
  • 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.
• Use Cloudinary client-side libraries:
  • Set "automateResponsivenessWithJS" to true.
  • Include "autoResponsiveDimensions" (see above).
  • You can exclude "dimensions" and "breakpoints" from the settings.

Use 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

Enabling Cloudinary on specific pages

You can choose on which pages you want to enable Cloudinary using the Cloudinary Image Page Type Settings custom preference. By default, Cloudinary is enabled on all page types.

Set "enabled" to true or false for each page type, for example:

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

Commonly-used Media Library features

With the B2C Commerce cartridge installed, you can open your Cloudinary Media Library from Merchant Tools > Cloudinary Admin > Media Library. You can access almost all of the same functionality that is available in the full Media Library in your Cloudinary Console.

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.

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.

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 Structured Metadata options in the asset toolbar. You can Edit Contextual Metadata via the (3-dot) options menu. The type of metadata available for editing (contextual or structured) depends on the setup for your organization's account.

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.

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.