commercetools extension developer guide

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

Optional parameters

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

Optional parameters

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.

Required parameters

Optional parameters

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.

Required parameters

Optional parameters

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

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.

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.

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 Displaying 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.

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.

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.

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.