More Products

Salesforce Commerce Cloud B2C Commerce Cartridge for Headless implementation

Last updated: Sep-02-2024

This guide provides detailed instructions for implementing a custom frontend using OCAPI's Cloudinary customizations.

Salesforce Commerce Cloud PWA Kit setup

Product Gallery and Video Player

If you have an existing SFCC PWA Kit storefront, implement the following code changes to integrate Cloudinary's Product Gallery and Video Player within your application.

Locate the necessary code snippets for each component within the app/components directory of the cloudinary_sfcc_pwa-kit GitHub repository. Comments such as {/** Cloudinary Custom Code Starts */} within the GitHub files indicate the relevant Cloudinary custom code.

Note
For more information about the Salesforce Commerce Cloud PWA Kit, see SFCC's Composable Storefront documentation.

Additional PWA Kit components

  • Cloudinary-content-asset (located at app/components/cloudinary-content-asset) is used for rendering content assets.

  • Cloudinary-content-slots (located at app/components/cloudinary-content-slots) is used for rendering content slots.

  • Cloudinary-image-gallery (located at app/components/cloudinary-image-gallery) is used for rendering Cloudinary image galleries on a PDP.

  • Cloudinary-image-swatches (located at app/components/cloudinary-image-swatches) is used for rendering Cloudinary swatches on a PDP.

  • Cloudinary-lineItem-image (located at app/components/cloudinary-lineItem-image) is used for rendering Cloudinary images on the cart, checkout, order confirmation, order history, and order detail pages.

  • Cloudinary-plp-images (located at app/components/cloudinary-plp-images) is used for rendering Cloudinary images on a PLP.

  • Cloudinary-product-video (located at app/components/cloudinary-product-video) is used for rendering Cloudinary videos on a PDP.

  • Cloudinary-widgets (located at app/components/cloudinary-widgets) is used for rendering Cloudinary galleries on a PDP.

  • item-variant/cld-item-image.jsx (located at app/components/item-variant/cld-item-image.jsx) is used to call the Cloudinary component to render Cloudinary images on the cart, checkout, order confirmation, order history, and order detail pages.

Setup for other frontend implementations

To integrate Cloudinary's Product Gallery and Video Player into your frontend application, for any frontend implementation besides the Salesforce Commerce Cloud PWA Kit, you must include the following Cloudinary scripts.

Product Gallery and Video Player scripts

To integrate Cloudinary's Product Gallery and Video Player into your frontend application, add the following JavaScript code:

Product Gallery scripts

To render the Cloudinary Product Gallery, add the following JavaScript code:

Note
The c_cloudinaryImage object contains the Product Gallery data retrieved from cloudinary.

Make sure to include a <div> with the <id> "cld-gallery" in your HTML code to indicate where the Cloudinary Product Gallery should be rendered:

Video Player scripts

To render Cloudinary videos, add the following JavaScript code:

OCAPI endpoints

With the B2C Commerce Cartridge for Headless cartridge configured, the standard OCAPI endpoints return Cloudinary objects with data about product media, in addition to the usual responses. You can use that information to embed Cloudinary components in your composable storefront.

Notes
  • With the B2C Commerce Cartridge for Headless installed and configured, your standard authentication to OCAPI provides access to the additional response information, as well.
  • You can alternatively use SCAPI to access Cloudinary information.

This chart summarizes the additional Cloudinary data that each endpoint returns, and links to more detailed descriptions:

Method Description
GET/products/{id} Returns the images, image gallery and videos from Cloudinary to be displayed on the Product Details page of a specified product.
GET/product_search/?folder=:folder Returns the product image search results to be displayed on the Product Listing page (PLP).
POST/search_suggestion Manages search suggestions based on Cloudinary images.
POST/baskets/{basket_id}/items Returns the Cloudinary images in the baskets on the Cart and Checkout pages.
GET/orders/{order_no} Returns the images, image gallery and videos from Cloudinary for an order product line item, order confirmation and order history.

product

Returns the images, image gallery and videos from Cloudinary to be displayed on the Product Details page of a specified product.

For detailed information about this endpoint including the non-Cloudinary information included in the response, see Products resource in the B2C Commerce documentation.

Syntax

GET http://hostname:port/dw/shop/v21_10/products/{id}

Response details

Cloudinary Attribute Attribute Details
c_cloudinaryImage This object contains data on all Cloudinary images and videos of all page types.
c_cloudinaryImage.cloudinaryImage Contains the Cloudinary image gallery.
c_cloudinaryImage.video Contains Cloudinary product video URLs.
c_cloudinaryImage.cldSwatches Contains data about Cloudinary product swatch images.
c_cloudinaryImage.cartImage Contains the product line item image for Cart.
c_cloudinaryImage.checkoutImage Contains the product line item image for Checkout.
c_cloudinaryImage.miniCartImage Contains the product line item image for Mini Cart.
c_cloudinaryImage.orderConfirmationImage Contains the product line item image for Order Confirmation.
c_cloudinaryImage.pdpSwatch Contains the site preference value for enabling/disabling product swatches on the PDP.
c_cloudinaryImage.images Contains the URLs of product images received from Cloudinary.
c_cloudinaryImage.isEnabled Contains the site preference value for enabling/disabling the Cloudinary cartridge.
c_cloudinaryImage.galleryEnabled Contains the site preference value for enabling/disabling the Product Gallery on the PDP.
c_cloudinaryImage.cloudName Contains the site preference value for the cloud name for rendering Cloudinary product videos.
c_cloudinaryImage.videoEnabled Contains the site preference value for enabling/disabling Cloudinary videos on the site.
c_cloudinaryImage.videoPlayerEnabled Contains the site preference value for enabling/disabling the Cloudinary Video Player on the site.
c_cloudinaryImage.pdp Contains the site preference value for enabling/disabling Cloudinary images on the Product Detail page.
c_cloudinaryImage.cartEnabled Contains the site preference value for enabling/disabling Cloudinary Cart images.
c_cloudinaryImage.isCheckoutEnabled Contains the site preference value of enabling/disabling Cloudinary Checkout images.
c_cloudinaryImage.miniCartEnable Contains the site preference value for enabling/disabling Cloudinary images on the add-to-cart model.
c_cloudinaryImage.orderConfirmation Contains the site preference value of enabling/disabling Cloudinary Order Confirmation images.
c_cloudinaryImage.orderHistory Contains the site preference value for enabling/disabling Cloudinary images on the Order history and Order Detail pages.
c_cloudinaryImage.randomNumber Contains the random number used for rendering Cloudinary videos on the PDP.

product_search

Returns the product image search results to be displayed on the Product Listing page (PLP).

For detailed information about this endpoint including the non-Cloudinary information included in the response, see ProductSearch resource in the B2C Commerce documentation.

Syntax

GET http://hostname:port/dw/shop/v21_10/product_search

Note
You can add search-related query parameters to the URL as well.

Response details

Cloudinary Attribute Attribute Details
c_cloudinaryImage Contains the Cloudinary product images for the Product Title Page.
c_cloudinaryImage.c_autoResponsiveDimensions Contains the Image Page Type Settings site preference for the PLP.
c_cloudinaryImage.plpEnabled Contains the site preference value for enabling/disabling Cloudinary features on the PLP.

search_suggestion

For detailed information about this endpoint including the non-Cloudinary information included in the response, see Search Suggestions in the B2C Commerce documentation.

Syntax

POST http://hostname:port/dw/shop/v21_10/search_suggestion

Response details

Cloudinary Attribute Attribute Details
c_cloudinaryImage Contains Cloudinary product images for search suggestions.
c_cloudinaryImage.suggestionEnabled Contains the site preference value for enabling/disabling Cloudinary product images in search suggestions.

baskets

Returns the Cloudinary images in the baskets on the Cart and Checkout pages.

For detailed information about this endpoint including the non-Cloudinary information included in the response, see Baskets resource in the B2C Commerce documentation.

Note
Headless Storefront doesn't provide an OCAPI call that returns the basket contents after an add-to-cart action. However, if using a non-headless frontend implementation, you can use this hook to render Cloudinary images on basket product line items.

Syntax

POST http://hostname:port/dw/shop/21_10/baskets/{basket_id}/items

Response details

Cloudinary Attribute Attribute Details
c_cloudinary Contains Cloudinary product image objects.
c_ cloudinary.miniCartImage Contains the product line item image for Mini Cart.
c_ cloudinary.cartImage Contains the product line item image for Cart.
c_cloudinary.checkoutImage Contains the product line item image for Checkout.
c_cloudinary.miniCartEnabled Contains the site preference value for enabling/disabling Cloudinary images on the add-to-cart-model.
c_cloudinary.cartEnabled Contains the site preference value for enabling/disabling Cloudinary Cart images.
c_cloudinary.checkoutEnabled Contains the site preference value for enabling/disabling Cloudinary Checkout images.

orders

If you're using a non-headless frontend implementation, then you can use this hook to render Cloudinary images on basket product line items.

For detailed information about this endpoint including the non-Cloudinary information included in the response, see Baskets resource in the B2C Commerce documentation.

Syntax

GET http://hostname:port/dw/shop/v21_10/orders/{order_no}

Response details

Cloudinary Attribute Attribute Details
c_cloudinary Contains Cloudinary product images objects.
c_cloudinary.orderConfirmationImage Contains the Cloudinary image for the Order product line item.
c_cloudinary.orderConfirmationEnabled Contains the site preference value for enabling/disabling Cloudinary on the Order Confirmation page.
c_cloudinary.orderHistoryEnabled Contains the site preference value for enabling/disabling Cloudinary on the Order History page.

Customizations

Customizations are hooks for triggering actions on different page types.

This table lists the customizations that are available per page type and describes how each script is mainly used:

Page Type Extension Point Cloudinary Extension Script Notes
Product Detail page dw.ocapi.shop.
product.modifyGETResponse
/int_cloudinary_headless/cartridge/
scripts/hooks/productDetails.js
Gets product images and videos from Cloudinary for PDP, Cart, Checkout, Order Confirmation, Order History, and Order Detail.
Product Listing page dw.ocapi.shop.
product_search.modifyGETResponse
int_cloudinary_headless/cartridge/
scripts/hooks/productSearch.js
Gets product images from Cloudinary and renders it on a PLP.
Search suggestions dw.ocapi.shop.
search_suggestion.modifyGETResponse
/int_cloudinary_headless/cartridge/
scripts/hooks/searchSuggestions.js
Gets Cloudinary images for Search Suggestions.
Cart and Checkout pages dw.ocapi.shop.
basket.items.modifyPOSTResponse
/int_cloudinary_headless/cartridge/
scripts/hooks/basket.js
Gets Cloudinary images for basket product line items.
Order Confirmation and History dw.ocapi.shop.
order.modifyGETResponse
/int_cloudinary_headless/cartridge/
scripts/hooks/order.js
Gets Cloudinary images for order product line items.

Non-product related assets

Cloudinary provides endpoints for rendering content assets and content slots that aren't related to a particular product. These endpoints must be triggered from the frontend when using PWA or any other type of frontend implementation.

The endpoint to obtain the Content Asset:

The endpoint to obtain the Content Slot:

Note
Currently, out of the box SFCC/SFRA Content Slots are available. You can create your own controllers or templates to render the slots.

✔️ Feedback sent!

Rate this page: