More Products

commercetools extension developer guide

Last updated: Jul-19-2024

The commercetools extension provides all the backend functionality needed to connect Cloudinary with commercetools and synchronize one way, from Cloudinary to commercetools. The Cloudinary assets are ready for you to render on your commercetools website or app.

To make that task easier, the extension provides several ready-to-use React components for displaying your Product Assets on the frontend. Get more information about the latest released version of the cloudinary_commercetools/components library on GitHub.

In addition, check out our demo app which showcases the use of these React components. Copy and paste relevant snippets from the source code for easy implementation.

commercetools extension React components

AssetRenderer

The AssetRenderer checks the Asset's tags and content type, determines if it’s an image, video or spinset and renders accordingly.

For each Asset in the array of Assets from commercetools, we display an AssetRenderer:

You can find an example on GitHub showing how the appropriate asset type is rendered on a carousel.

Required parameters

Parameter Type Description
asset Object The asset that you want to display in the component.

Optional parameters

Parameter Type Description
width Number The width of the displayed asset.
height Number The height of the displayed asset.
isThumbnail Boolean If true, a small version is displayed.
className String Adds classes to the rendered output.

AssetImage

The AssetImage renders a full size image or a thumbnail version, depending on the input. If no width or height is provided, the default image size is 600x700 or 136x142 for thumbnails.

Required parameters

Parameter Type Description
publicId String The public ID of the asset that you want to display in the component.

Optional parameters

Parameter Type Description
width Number The width of the displayed asset.
height Number The height of the displayed asset.
isThumbnail Boolean If true, a small version is displayed.

Note
An additional call is made to the Cloudinary API requesting the asset's original dimensions and calculating how much bandwidth was saved by requesting an optimized Cloudinary version. This information is displayed when you click on the (i) icon in the top-left corner.

AssetVideo

The AssetVideo will display a video component at the requested width and height. If no width or height is provided, the default image size is 600x700 or 136x142 for thumbnails.

For the thumbnail, the component overlays an additional image to serve as the play button.

Note
Make sure you upload a play button image to your product environment whose public ID matches the name specifying the overlay image in your code, for example play-icon-white-png-8_jajw2z in this hardcoded overlay.

Required parameters

Parameter Type Description
publicId String The public ID of the asset that you want to display in the component.

Optional parameters

Parameter Type Description
width Number The width of the displayed asset.
height Number The height of the displayed asset.
isThumbnail Boolean If true, a small version is displayed.

AssetSpinset

An AssetSpinset allow your users to spin a product around a central axis. In order to display a 360 spin set, the Product Gallery widget fetches all images with a particular tag (e.g. "lowtopsneakerspinset") and combines them into a single entity, where each image is included as a single frame of the resulting 360 spin set (sorted alphanumerically by their public ID).

For the thumbnail, the component overlays an additional image to serve as the navigation button.

Note
Make sure you upload a navigation button image to your product environment whose public ID matches the name specifying the overlay image in your code, for example 360-overlay-black_mjok7x in this hardcoded overlay.

Required parameters

Parameter Type Description
id String A unique identifier for your spinset, in case there are multiple spinsets on the page.
publicId String The public ID of the asset to use as the thumbnail in your spinset.
tags String array All the tags in the Cloudinary asset.
The asset will be used in the spinset if the unique spinset-tag exists in the array.

Optional parameters

Parameter Type Description
width Number The width of the displayed asset.
height Number The height of the displayed asset.
isThumbnail Boolean If true, a small version is displayed.

Only one of the spinset images must be linked to a commercetools Product Assets because the rest of the spinset is loaded directly from Cloudinary.

Product Asset information

To set your components, whether they're commercetools extension React components or custom, you need to pass information about your Products and their associated Assets. In your project, there are many ways that you might retrieve this information, for example via your own API that interfaces with commercetools.

The following example shows how to get that information by sending a request to the relevant commercetools endpoint.

Example

To select a commercetools Product by ID, send the following HTTP request:

You can then retrieve its Product Assets by specifying product.masterData.masterVariant.assets

Sample response

Note
See the commercetools documentation for more information on how to get information about your Products.

Use cases

The following sections highlight just a few ways to use the commercetools extension's capabilities in your storefront. You can choose to implement any of these use cases, and you can customize any solution based on your own specific needs.

Render a Cloudinary Product Gallery for your PDP

This integration provides a helper method for passing commercetools Product Asset information to the Cloudinary Product Gallery.

As input, you need to provide commercetools Product Asset information. Assets are found on the Products in commercetools, at the level of Variants. For example:

  • Product 'Tie printed maxi dress'
    • Variants
    • SKU 11001 (Red, size 38)
    • SKU 11002 (Red, size 39)
    • SKU 11003 (Red, size 40)
    • SKU 11011 (Black, size 38)
    • ...

Every Variant has a list of Assets. Each Asset has:

  • An array of sources, each with:
    • A URI, in which we store the public ID of Cloudinary asset.
    • The content type, which tells us if the asset is an image, a video or something else.
      Note
      commercetools Assets support multiple sources used to store information, e.g., different sizes. However, the provided helper method uses the automatic resizing and therefore takes only the first element in the array of asset sources.
    • A name.
    • An array of tags that contains the Cloudinary tags for this asset.

Notes

Render a custom product gallery for your PDP

To render a custom product gallery, follow the following steps:

  1. Get Product Asset information.
  2. From the response, retrieve:
    • The id of the asset.
    • The uri of the asset.
    • The contentType of the asset.
  3. You can use the commercetools extension AssetImage, AssetVideo and AssetSpinset components to render the images, videos and spinsets for your product gallery.
    • Set an asset as the thumbnail by setting the isThumnail parameter to true.
    • Control the size of your assets by setting the width and height parameters.
  4. Determine the asset type to make sure you render it with the compatible component. Do this automatically with the AssetRenderer component or manually by checking the contentType parameter for the asset.
  5. Use the information you retrieved to display the assets on your custom product gallery.

Note
The demo app uses the Cloudinary Product Gallery exclusively and as such doesn't showcase a custom product gallery.

Render a product image on your PDP and PLP

  1. Get Product Asset information.
  2. From the response, retrieve:
    • The id of the asset.
    • The uri of the asset.
    • The sortOrder of the asset (if rendering the image on a PDP).
  3. Use the commercetools extension AssetImage React component to render the individual images for your product gallery in the specified order or render the images on your PLP per product.
    Note
    For more information about rendering images on a Cloudinary Product Gallery, see Dislaying assets.
  4. Optionally set an asset as a thumbnail by setting the isThumnail parameter to true.
  5. Optionally control the size of your asset by setting the width and height parameters.
  6. Make sure the asset is an image before rendering it with the AssetImage component. Do this automatically with the AssetRenderer component or manually by checking the contentType parameter for the asset.

Note
To see an example of how an image is rendered using the AssetImage component, see the Cloudinary demo app and source code.

Render videos on your PDP

  1. Get Product Asset information.
  2. From the response, retrieve:
    • The id of the asset.
    • The uri of the asset.
    • The sortOrder of the asset.
  3. Use the commercetools extension AssetVideo React component to render the individual videos for your product gallery in the specified order.
    Note
    For more information about rendering videos on a Cloudinary Product Gallery, see Videos.
  4. Optionally set an asset as a thumbnail by setting the isThumnail parameter to true.
  5. Optionally control the size of your asset by setting the width and height parameters.
  6. Make sure the asset is a video before rendering it with the AssetVideo component. Do this automatically with the AssetRenderer component or manually by checking the contentType parameter for the asset.

Note
To see an example of how a video is rendered using the AssetVideo component, see the Cloudinary demo app (select the video component) and source code.

Render 3D models and 360 spinsets

  1. Get Product Asset information.
  2. From the response, retrieve:
    • The id of the asset.
    • The uri of the asset.
    • The sortOrder of the asset.
  3. Use the commercetools extension AssetImage or AssetSpinset React component to render the individual assets for your product gallery in the specified order.
    Note
    For more information about rendering spinsets on a Cloudinary Product Gallery, see 360 spin sets.
  4. Optionally set an asset as a thumbnail by setting the isThumnail parameter to true.
  5. Optionally control the size of your asset by setting the width and height parameters.
  6. Determine the asset type to make sure you render it with the compatible component. Do this automatically with the AssetRenderer component or manually by checking the contentType parameter for the asset.

Notes

Render responsive images, videos, and Product Galleries

All commercetools extension React components are based on Cloudinary capabilities and are automatically fully responsive.

For more information about rendering responsive images, videos and spinsets in the Product Gallery, see Responsive assets.

Setting alt-text

  1. Get Product Asset information.
  2. From the response, retrieve:
    • The id of the asset.
    • The uri of the asset.
    • The altText of the asset.
  3. Use the commercetools extension AssetImage React component to render the individual images for your product gallery along with their specified alt-text.

Note
The demo app uses the Cloudinary Product Gallery exclusively and as such doesn't use this component. However, you can see the single line of code needed implement this.

✔️ Feedback sent!

Rate this page: