Generating previews
- Last updated on May 15, 2025
- •
- 3 minutes to read
Some assets, like designs, images, or fonts, may have previews. Previews are generated only once, and information about them is automatically added to the asset metadata. If you update an asset file (for example, modify the design), the preview is invalidated and automatically removed.
Each asset may contain more than one preview. For example, it may be a preview for an admin app or for a storefront, or perhaps a storefront app may require a small thumbnail and a larger preview.
"previews": {
"<namespace>-<name>": {
"id": "6064221fe810853799cbf2f3",
"name": "<name>",
"namespace": "<namespace>",
"width": 248,
"height": 141,
"url": "<URL>"
}
}
Here, the <namespace>
is a unique application name, for example, online-store
, backoffice
, mystore
, etc. The <name>
specifies a preview type (like thumbnail
, websized
, tiny-icon
, etc.).
To make Customer's Canvas generate a preview, you need to use the Asset Processor API. It has the endpoint GET /api/processor/v1/designs/{id}/preview/{namespace}/{name}/{width}x{height}
, where you can specify the namespace
, name
, width
, height
, and some other parameters, and then it will generate the preview and update the metadata.
curl -X \
GET "https://api.customerscanvashub.com/api/processor/v1/designs/617a4fdd1079e200f24ffeb2/preview/mystore/thumbnail/160x120" \
-H "accept: application/octet-stream" \
-H "Authorization: Bearer <TOKEN>"
You don't have to re-request a design element after that. This endpoint returns a preview as a stream that can be sent to a browser right away. Also, there is a version of this endpoint that returns the result as a URL: GET /api/processor/v1/designs/{id}/preview/{namespace}/{name}/{width}x{height}/url
.
This way, the workflow is the following:
- Request a design entry.
- Check whether the
metadata.preview["<your_namespace>-<preview_name>"]
is not empty. - If you find the preview information, read its
url
property and insert the acquired URL into the<img>
tag. - Otherwise, send a request to Asset Processor and use its output instead of the URL extracted from metadata. Customer's Canvas will automatically add preview information to the design metadata, and it will be recognized the next time Step 2 is performed.
Further Reading
- Explore how to create new designs using this API.
- Learn how to import already created designs to storage.
- Dive into Asset Processor API reference.