commercetools extension developer guide
Last updated: Sep-02-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. |
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.
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.
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
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.Notecommercetools 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.
- For more information about rendering a Cloudinary Product Gallery, see Product Gallery.
- To see an example of how a Cloudinary Product Gallery is rendered, see the Cloudinary demo app and source code.
Render a custom product gallery for your PDP
To render a custom product gallery, follow the following steps:
- Get Product Asset information.
- From the response, retrieve:
- The
id
of the asset. - The
uri
of the asset. - The
contentType
of the asset.
- The
- 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 totrue
. - Control the size of your assets by setting the width and height parameters.
- Set an asset as the thumbnail by setting the
- 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. - Use the information you retrieved to display the assets on your custom product gallery.
Render a product image on your PDP and PLP
- Get Product Asset information.
- 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).
- The
- 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.NoteFor more information about rendering images on a Cloudinary Product Gallery, see Dislaying assets.
- Optionally set an asset as a thumbnail by setting the
isThumnail
parameter totrue
. - Optionally control the size of your asset by setting the width and height parameters.
- 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
- Get Product Asset information.
- From the response, retrieve:
- The
id
of the asset. - The
uri
of the asset. - The
sortOrder
of the asset.
- The
- Use the commercetools extension AssetVideo React component to render the individual videos for your product gallery in the specified order.NoteFor more information about rendering videos on a Cloudinary Product Gallery, see Videos.
- Optionally set an asset as a thumbnail by setting the
isThumnail
parameter totrue
. - Optionally control the size of your asset by setting the width and height parameters.
- 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
- Get Product Asset information.
- From the response, retrieve:
- The
id
of the asset. - The
uri
of the asset. - The
sortOrder
of the asset.
- The
- Use the commercetools extension AssetImage or AssetSpinset React component to render the individual assets for your product gallery in the specified order.NoteFor more information about rendering spinsets on a Cloudinary Product Gallery, see 360 spin sets.
- Optionally set an asset as a thumbnail by setting the
isThumnail
parameter totrue
. - Optionally control the size of your asset by setting the width and height parameters.
- 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.
- To see an example of how a 360 spinset is rendered using the AssetSpinset component, see the Cloudinary demo app and source code.
- Use the Asset Spinset component to render a 3D model. See the Cloudinary demo app and source code.
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
- Get Product Asset information.
- From the response, retrieve:
- The
id
of the asset. - The
uri
of the asset. - The
altText
of the asset.
- The
- Use the commercetools extension AssetImage React component to render the individual images for your product gallery along with their specified alt-text.