Using assets to save links to images, videos and pdfs
The commercetools platform offers the common type Asset that is embedded in other endpoints like the Products. To follow this tutorial, you should have a project set up, as described in Getting Started, and have a product onto which you want to add assets.
Adding an asset
Let’s add a simple asset, a PDF, to our product variant:
We’ve set a name and a description. We’ve also added tags and set the optional contentType on the source. Both can be used by your frontend to decide how to display the asset, or search for a specific one in the assets array. For example, if there is a Manual-Section on your PDP, you can search for all assets that have the tag “manual”, and based on the contentType decide whether to show the content in a PDF viewer or a video player.
Here are a two examples for the use of tags. You can use them whenever you want to help your frontend to display the assets.
Using tags for languages
You may add a tag for the language of the asset. For example, a video may be localized into different languages. With the help of a tag, the frontend can pick the right asset to display.
Using tags for images in different aspect ratios
Depending on the device or view, you may want to present the content in a different aspect ratio. E.g. on a desktop, the landscape version of an image is shown, but on a mobile device the portrait version is preferred.
In this example, the primary image exists in two versions - landscape and portrait.
Using tags for 360 degree images
For 360 degree images, you will have multiple assets (e.g. you may shoot an image at every 10 degrees). With the tags, your frontend can figure out which of the assets make up the 360 degree image, and in which order.
In this example, the first image is a regular one. The following ones belong to the 360 degree image, and indicate with a tag at which angle they’ve been shot.
Using Asset Sources
An AssetSource is a representation of an Asset in a specific format, e.g. a video in a certain encoding, or an image in a certain resolution. To pick the right source, you can optionally supply a key or the dimensions of the asset.
Using Asset Sources for offering an image in different resolutions
In this example, the image is available in three resolutions: One is a thumb to be displayed on a POP, one is a regular resolution to be displayed on a PDP, and one is a high-res version to be used when the customer zooms into the image.
In this example, both the key and the dimensions are set. The frontend may use the key to find the thumbnail by finding the source for which the key is "thumb". Alternatively, one could save many resolutions, and the frontend could figure out which image is best used (e.g. a thumbnail on a retina-display would use a different resolution than on a regular display).
You can also use the dimensions field to generate the HTML srcset property:
Using Asset Sources for offering a video in different encodings
In this example, the video is encoded for in MP4 (for Flash), WebM (for HTML5) and HLS (for mobile apps). A thumbnail is also available.
The flash player or a mobile app could look for its file by the key. In HTML5, the video element supports multiple sources and the browser will pick the most suitable source:
You’ve seen how to create a simple asset like a PDF, how a frontend can select the right asset out of multiple ones based on tags, and how asset sources can be used to offer different image resolutions or video encodings.