Dynamic Imaging Service

Use the B2C Commerce Dynamic Imaging Service when storefront code must request a specific image size, crop, or format with URLUtils or MediaFile. The B2C Commerce Dynamic Imaging Service eliminates the need to upload different-sized images to meet your storefront requirements.

Which Salesforce Commerce Product Do I Have?

After you upload a high-resolution source image, Dynamic Imaging formats the correct size for each image application: your product page, catalog page, recommended products, search results, and so on. Transformation applies only to images hosted in B2C Commerce. An external image returns the plain URL, with no error. Transformation also runs only when Dynamic Imaging Service is available for the instance. Otherwise, the API returns a standard static content URL.

For example, you have a storefront with a product catalog of 100,000 items. Your web design supports images up to 150 x 150 pixels, and displays four images per row of a customer’s search results. Your web designer creates a different layout, and now a product search displays only three images sized 250 x 250 pixels per row. Instead of uploading the resized images, the Dynamic Imaging Service resizes the existing ones.

For Storefront Next, see Images. The image transformation URL comes from the SCAPI response, the same way it does for PWA Kit. For Composable Storefront, see Performance Best Practices. Apply parameters to control image size, crop, overlay, format, background color, and quality settings.

How Do I Create an Image Transformation URL for B2C Commerce Images?

In B2C Commerce, the URLUtils and MediaFile classes dynamically generate multiple image resources from a single high-resolution image. An image transformation URL identifies the cacheable resource and specifies how to transform it.

Use these classes because the API validates the transformation parameters and protects you from future changes to the basic URL pattern. Generate image URLs at run time with URLUtils and MediaFile, or take them from an OCAPI product response. Do not paste /dw/image/v2/, a tenant ID, or an infrastructure hostname into a template. A hard-coded URL can break when the vanity domain, environment suffix, or resource fingerprint changes.

URLUtils and MediaFile are Script API calls for SFRA and SiteGenesis. The recommended path is those classes. The community product image wrapper is an optional sample only if that repository is still supported.

The JavaScript object literal contains transformation parameters. Each method returns a URL derived from your transformation parameters. If you don’t pass parameters to the Dynamic Imaging Service, the image passes through in its original configuration.

Example: The URL parameter cy replaces the transformation parameter cropY.

The URLUtils class includes these methods for generating image transformation URLs.

1public URL imageURL( String path, Object transform );
2public URL imageURL( String context, String contextID, String relPath, Object transform );
3public URL absImage( String path, Object transform );
4public URL absImage( String context, String contextID, String relPath, Object transform );
5public URL httpImage( String path, Object transform );
6public URL httpImage( String context, String contextID, String relPath, Object transform );
7public URL httpsImage( String path, Object transform );
8public URL httpsImage( String context, String contextID, String relPath, Object transform );

The MediaFile class includes these methods for generating image transformation URLs.

1public URL getImageURL( Object transform );
2public URL getAbsImageURL( Object transform );
3public URL getHttpImageURL( Object transform );
4public URL getHttpsImageURL( Object transform );

getURL, getAbsURL, getHttpURL, and getHttpsURL take no arguments. They return the file URL without a transformation.

Sample Calls

In B2C Commerce, this call to URLUtils.imageURL(String path, Object transform):

1URLUtils.imageURL( '/<static image path>/image.png', { scaleWidth: 100, format: 'jpg' } );

Returns the image transformation URL.

1http://<image server host name>/dw/image/v2/.../on/demandware.static/.../<static image path>/image.jpg?sw=100&sfrm=png

This call to MediaFile.getAbsImageURL(Object transform) requests the default product image:

1product.image.getAbsImageURL( { scaleWidth: 100 } );

For a named view type, get that image first. The first image in a view type is index 0. A variation product resolves to images assigned on the base product. There is no pattern-based image lookup.

1var largeImage = product.getImage('large', 0);
2largeImage.getAbsImageURL({ scaleWidth: 100 });

Returns the image transformation URL.

1http://<image server host name>/dw/image/v2/.../on/demandware.static/.../<path to product image>/FG45SDAF.jpg?sw=100

Which Transformations Are Supported?

In B2C Commerce, these parameters control a Dynamic Imaging Service transformation.

Type	Transform object parameters (URL parameters in brackets)	Description
Scale	`scaleWidth (sw)`, `scaleHeight (sh)`, `scaleMode (sm)`	The `scaleWidth` and `scaleHeight` parameters are integers. Valid values are 10 through 3000 pixels. Use `scaleMode` only when combined with `scaleHeight` and `scaleWidth`. Setting one of these parameters triggers a scaling operation. If you provide both values, the smaller value determines the resize amount. Dynamic Imaging crops the image based on the second dimension, centering the cropped area. If the parameter enlarges the image, it’s enlarged only if the result isn’t larger than 3000x3000 pixels. The default parameter for `scaleMode` is `cut`. If you set `scaleMode` to `fit`, it scales the image to the box dimensions that you enter while maintaining the aspect ratio. The result is a smaller image in one dimension.
Overlay	`imageX (ox)`, `imageY (oy)`, `imageURI (oimg)`	The `imageX` and `imageY` parameters are integers, 0 or greater. Supported formats are GIF, PNG, JPG, and JP2. Because an animated GIF can cause frame artifacts, maintain the aspect ratio for an animated GIF. Set the `imageURI` parameter to the absolute path of the overlaid image. The `imageURI` parameter requires proper URL encoding and can’t exceed 400 characters. The path must support query string parameters that Dynamic Imaging Service supports. Use a transformed image for the overlaid image. If the overlaid image extends beyond the primary image’s boundaries, Dynamic Imaging Service crops the overlaid image to match the primary image’s dimensions. The `oimg` overlay value must point to a customer-owned image served by the Dynamic Imaging Service domain.
Crop	`cropX (cx)`, `cropY (cy)`, `cropWidth (cw)`, `cropHeight (ch)`	The `cropX`, `cropY`, `cropWidth`, and `cropHeight` parameters are integers. Specify all four parameters to trigger a cropping operation. The values for `cropX` and `cropY` must be 0 or greater. If the crop location is outside the image area, nothing is cropped. The value for `cropWidth` and `cropHeight` must be 10 or greater. If the specified size is greater than the original image, the crop area is reduced to the actual image area.
Format	`format (sfrm)`	The format parameter specifies the image’s target format. Supported target formats are AVIF, gif, jp2, jpg, jpeg, jxr, png, and WebP. The generated URL path uses the file extension of the target format. If you don’t specify a target format, the conversion isn’t performed. The path parameter (when using the `URLUtils` class methods) or attribute value (`MediaFile` class) references the source image. The source image format recognizes these file extensions: gif, jp2, jpg, jpeg, png, tiff, tif, webp, and avif. Provide the source format in the `sfrm` URL parameter.
Quality	`quality (q)`	The quality parameter specifies a quality setting for JPG and JP2 images and the compression level for PNG images. For JPG and JP2 images, set values from 1 to 100 for the highest quality. The default is 80. Omit the value to keep the default. For PNG images, the quality setting has no effect on the appearance of the PNG because the compression is always lossless. Instead, use the quality setting to set the zlib compression level and filter type as a two-digit number. The first digit sets the zlib compression level (1-9). The second digit sets the filter type. If the PNG setting isn’t provided or is set to 0, the default value is 75. If this setting is set to 100 (a three-digit number), it actually equals the quality setting 90.
Metadata	`strip`	The strip parameter specifies whether to strip metadata, such as EXIF and color profiles, from the image during transformation. Valid values are `true` or `false`. The default is to strip data (`true`).
Background	`bgcolor`	The `bgcolor` parameter specifies the background color for images that support transparency or JPEG images that are converted from a format that supports transparency. Enter a six-digit hexadecimal RGB value. For PNG images, also apply an optional two-character alpha value to specify transparency. For example, `FF0000` = Red; `FF000077` = Red with 50% transparency. If the alpha value is omitted, the resulting color is opaque. Explicitly passing `00` as the alpha value achieves the same result. Alpha values are valid only when the image output format is PNG.

Storefront Next sends q=70 unless you set images.quality or the image URL already includes q. A q already in the URL wins. If you omit q from a URLUtils or MediaFile call, the image server applies its default, documented as 80.

What Limits and Caching Rules Apply?

In B2C Commerce, Dynamic Imaging Service applies these limits.

File size: Images over 10 MB aren’t transformed and they’re served in their original configuration. The first request for an oversized image returns an error, but subsequent requests return the images in their original configuration.
Dimensions: The maximum transformable size is 3,000 x 3,000 pixels.
Timeout: If a transformation doesn’t complete within 29 seconds, Dynamic Imaging Service returns error 408. Avoid expensive transformations like upsizing animated GIFs.
Browser blocking: In nonproduction environments, Firefox Tracking Protection blocks first-time transformations in some circumstances. To avoid this blocking, set Tracking Protection to Never during testing.

Dynamic Imaging Caching

In B2C Commerce, the Dynamic Imaging Service uses caching to serve images to browsers and apps.

Content Delivery Network (CDN) instances: Images are cached until a cache invalidation is requested. New image assets are given a unique cache identifier and don’t require explicit cache invalidation.
Non-CDN instances: The Dynamic Imaging Service revalidates images after 10 minutes.