Documentation

Best Practices

While there are no strict requirements on how to use ImageEngine, below is a list of best practices to get the most out of ImageEngine. In general, these best practices will address and improve many of the “Core Web Vitals” reported in many web performance audit tools.

# Always define display size of images

In your markup, you should always specify a display pixel size (width and height) in the image tags. Either by the width attribute or CSS styles. Additionally, if you’ve implemented Responsive Images on your site, include the sizes attribute. Doing so will prevent unnecessary Cumulative Layout Shifts of the webpage.

In some cases, ImageEngine may return a bigger image than expected to cater to high DPI screens. If the design of the page expects a 400 pixel wide image and ImageEngine returns an 800 pixel wide image for devices with a pixel ratio of 2, the design may be broken if the markup does not define a display size of the image. Similar situations may occur when using Client Hints.

# Origin image in high resolution

If your publishing -system or -workflow supports it, and based on the design of you page, origin images should be of higher resolution than you strictly need. For example, if your design has a hero image with a display width of 1000 pixels (CSS pixels), ImageEngine will try to serve this image at 2000 pixels width for screens with a pixel ratio of 2. Because ImageEngine does not scale images up, the origin image must be at least 2000 physical pixels wide in order to get the best possible quality. See also Client Hints.

# Use Auto mode

In most cases using ImageEngine without directives is the best option. Only use directives for specific cases. When you use directives, some, or all, of the built in optimization logic may not be applied. For example, if you specify /f_webp/ all devices/browsers, even those not supporting webp, will be served a webp image.

# Use Resource Hints

Resource Hints will speed up the connection to ImageEngine by telling the browser as early as possible to connect to the ImageEngine server. This way, the browser will have the connection open when it is needed later. Resource hints are enabled in the <head> section of your markup this:

<link rel="preconnect" href="//images.example.com">

Or alternatively in the HTTP response headers of your web server like this:

Link: <//images.example.com>; rel=preconnect

# Use Responsive Images

The main reason why ImageEngine benefits from Responsive Images syntax is Client Hints. You can read more about Responsive Images and ImageEngine below.

Summarized, the w_auto directive, and the sizes attribute is key. Here is an example:

<img src="//images.foo.com.imgeng.in/w_auto,800/http://wurfl.github.io/i/pencilsx.jpg" sizes="90vw">

or using the querystring:

<img src="//images.foo.com.imgeng.in/image.jpeg?imgeng=w_auto,800" sizes="90vw">

If you need different sized images to be served, depending on viewport size, you can use media queries in the sizes attribute.

Usually, the results are over all better when ImageEngine get to decide how to optimize the image. That means no URL parameters or directives are required, just the plain image url:

<img src="//images.foo.com/img.png" alt="Image optimized with ImageEngine" width="100%" sizes="(min-width: 850px) 840px, calc(100vw - 10px)">

Note the presence of the sizes attribute. When sizes is present, the browser is able to calculate the intended display size of the image before making the request to download it. This is the prerequisite for the browser to add client hints to the request. Client hints enable ImageEngine to be much more accurate when resizing and optimizing images.

In your responsive images markup, with or without client hints enabled, it may make sense to use ImageEngine url parameters to request specific sizes of an image:

<img
 src="//images.yoursite.com/camera.jpg"
 sizes="(min-width: 850px) 840px, calc(100vw - 10px)"
 srcset="//images.yoursite.com/camera.jpg?imgeng=/w_375 375w,
         //images.yoursite.com/camera.jpg?imgeng=/w_768 768w"
 alt="ImageEngine with srcset">

Note: ImageEngine will still convert to the best image format whether it is webp, jpeg2000 or something else.

# Use Native Lazy Loading

Lazy loading if images might be a good idea, but should be used with causion. As a rule of thumb; do not use a 3rd party JavaScript library to manage image loading. The reason for this is that it breaks the built in image loading featurs in the browser which may make image loading, especially above the fold slower both becaue the browser starts the download later and becasue the browser first has to execute the JavaScript.

For images served with ImageEngine, especially images visible above the fold or near the top of the page, the best practice is to avod using 3rd party lazy loading JavaScript libraries. If you still want to use lazy loading for images below the fold, you should use native lazy loading.

Images not visible on the initial screen or lower on the page, should of course be loaded on demand.

# Use Client Hints

Client Hints enable the browser to send more detailed information about what size the image should be, relative to the viewport size, actual display size, screen resolution and network quality.

To enable Client Hints for your site you’ll have to explicitly enable it by adding the below <meta> tag to your <head> element:

<meta http-equiv="Accept-CH" content="viewport-width, width, device-memory, dpr, downlink, ect">

or adding a HTTP header in the response of the html:

Accept-CH: viewport-width, width, device-memory, dpr, downlink, ect

When the resposne from the webserver to the browser contains this header, the browser will send the requested client hints on all subsequent requests as feature- or permission policies allows.

However, to enable the browser to send client hints to 3rd party locations like the ImageEngine delivery address, for example images.foo.com or xxzzyy.cdn.imgeng.in, your server must also delegate access to the selected client hints to the ImageEngine delivery address. This is done using Feature Policies or Permission Policies. This is yet another response HTTP header looks like this assuming the ImageEngine delivery address is images.foo.com:

Feature-Policy: ch-viewport-width https://images.foo.com;
ch-width https://images.foo.com;
ch-dpr https://images.foo.com;
ch-device-memory https://images.foo.com;
ch-ect https://images.foo.com;
ch-downlink https://images.foo.com

Remember to prefix the actual client hints with ch- and use lowercase.

Note: The Feature Policy specification a living standard and is likely to change. This documentation will however reflect what is impelemented in the wild. It is likely that the name of the header will change to Permission-Policy in the near future. Currently, Chromium only supports Feature-Policy to delecate client hints.

Using client hints and ImageEngine with responsive images will generate a perfectly sized and optimized image. However, note that the Width header is only sent if the browser is able to determine the intended display size of the image. Hence, you must provide a sizes attribute to the image tags. It is OK to “retrofit” responsive images by copying the value of any width attribute (px) to the sizes attribute: <img sizes="100px" width="100">.

ImageEngine will only return Content-DPR when Width header is present in the request. If the origin image is smaller than the intended display size, Content-DPR will be < 0 because ImageEngine does not scale images larger than the original size.

Here is an example implementation.

The Client Hints specification can be found here. For more details, please read this article on Client Hints, Responsive Images and ImageEngine.

Other resources: