Watch this short video to learn how to add an Engine setting
Usually, it is recommended to let ImageEngine make all the decisions on how to best optimize an image. ImageEngine’s advanced algorithms for choosing the best optimization strategy give much better results than micromanaging each individual image.
If modifying ImageEngine’s behavior is required for single images (for instance, forcing a particular size, or conversion to a certain filetype), it is preferable to use our in-line URL Directives. Please see our article for more information on using URL directives.
However, there are valid scenarios (such as when a particular override is desired for a large, definable set of images) where the best option is to adjust the default behavior of ImageEngine. In addition to modifying image delivery, our Engine Settings also allow for the override of other behaviors, such as setting Minimum Cache TTL and some other options.
Note that settings may take up to 15 minutes to spread to all edges on the CDN.
Accessing Engine Settings
To customize an Engine’s behavior, click the “Engine Settings” button while you are viewing the Engine's overview page:
or, select “Settings” from the sidebar while the Engine's drop down list is open:
Then select the "Advanced Settings" tab:
The Settings Page
On the right-hand side of the Advanced Settings tab, you will find a list of all the custom configurations that are currently in place for the Engine.
When an Engine is first created, nothing will be in place, and ImageEngine is considered to be in "auto mode".
Existing Settings may be edited or deleted using the buttons on their card. Click 'edit' to view the configuration. While viewing a configuration, note that the tab displays "Edit configuration". If any changes are made, make sure to click "Update". Click Close to return to "Add custom configuration" mode.
Adding a new custom configuration
Ensure that the advanced settings tab is displaying "Add Custom Configuration" if not, click `close` to return to the "Add custom configuration" mode.
Give the new setting a descriptive name (a date is helpful, too!), and define a “path” that the settings will be applied to must be specified.
For instance, in the example above, the configuration will apply to any images that are stored within the folder
The 'Path' is an expression, composed of forward slashes, asterisks, and other symbols to define what will be affected by the setting. Whenever there is a match with the path of the request, if the settings are applicable to the file, they will be applied. A path with a query string is also supported.
The default path can be considered to be
/**/*, which will affect all images served through the Engine. By comparison,
/**/*.jpg would effect only .jpg files
A list of Path options and Path examples may be found in this article: Path Examples and Operators.
Validate the Provided Path
Once a path has been entered, the Path Validation modal may be used. Click the checkbox icon to open the Path Validation window.
The path validation window:
In the text field, you may enter a sample URL to check if an image would be caught in the Path.
Click the “Validate” button to test whether the path will catch the URL specified. If the validation was successful, a success message will appear.
Note: When validating, please note that it is not necessary to provide the domain of the example path, nor indeed, is it required to use a real image URL.
Once you are done defining the configuration, click the "Save" button. The new custom configuration is then added to the list on the righthand column. Settings are locked for a short period after saving.
Descriptions of Available Adjustable Engine Settings
Set Minimum Cache TTL
By default, ImageEngine honors the expiration directives given by the HTTP response of the origin, using the provided Time To Live(TTL) to decide how long the object will be stored by ImageEngine.
This setting allows you to override that behavior and set a different minimum TTL in seconds.
Time to live directly impacts your site’s page load time (i.e., cached data loads faster), as well as content freshness (i.e., data cached for too long can become stale).
The minimum allowed TTL is 3600 sec (1 hour). It is recommended to use at least 7776000 (90 days) as cache TTL. Even higher numbers may be beneficial, as it will allow us to retain images for longer in the cache, further reducing cache misses and traffic to the origin.
This value populates the s-maxage attribute to the Cache-Control response header (only applies to shared caches (e.g., proxies) and is ignored by a private cache).
Set Minimum Browser Cache TTL
Similar to the above setting, ImageEngine honors the cache expiration directives given by the HTTP response of the origin and mirrors this all the way to the end user’s browser. This Setting allows for an override to those headers if the value of the Cache-Control header from the origin web server is less than the Minimum Browser Cache TTL setting or if the origin web server does not send a Cache-Control or an Expires header.
This value populates the s-maxage attribute to the Cache-Control response header and defines for how many seconds the object may be cached in the browser. The recommended TTL is 7776000 seconds (90 days) or longer.
Image Size and Quality
Set the image size and quality for all images returned by ImageEngine matching the URL path provided.
You can either force a specific width and/or height or apply automatic resizing with a custom fallback width to all images matching the provided Path.
In case you want to force both a specific width and height, you may also choose a fit method (the image will be fitted on the canvas defined by the width and height).
In auto mode, width fallback with other sources of size information (WURFL or Client Hints) will be tried first, but if nothing is found, the provided width will be the fallback width. 2560px is default.
Set Max DPR (Device Pixel Ratio)
Most screens today, mobile or desktop, are high resolution where multiple device pixels correspond to less display pixels. DPR is today ranging form 1 t0 >5. In reality it is hard for the human eye to notice any visual difference when DPR is >2.
This setting enables you to set a maximum DPR value which ImageEngine should consider when optimizing images. This will significantly reduce image payload for large origin images without affecting the perceived visual quality. The recommended value is 2.1.
You can choose to adjust the relationship between low image byte size and image quality. You can specify an overall compression rate.
Keep EXIF Data
By default, ImageEngine removes all metadata embedded in an image except for copyright data. By activating this setting, all metadata will be preserved. If your application makes use of embedded metadata (for example, location), you should enable this setting.
Pass Images Through
Enable this option if you want images to be served unchanged by ImageEngine. If enabled, ImageEngine will still cache the original image, but will not apply any optimizations. This setting is disabled by default. Selecting "Custom" will cause it to enable.
Override the amount of sharpening applied to an image on a scale from 1 to 100, where 100 is the maximum value for sharpening.
Temporarily Serve Origin Image
If enabled, ImageEngine will serve the original, unmodified image if an optimized version is unavailable. This will usually affect the very first request for an image.
You can specify the Time To Live (TTL) for the original image to be kept in the edge cache before the edge cache again checks to see if there is an optimized version available. The default is 180 seconds.
Enabling this feature will make sure that image delivery is not delayed by the initial processing.
Scenarios when enabling this feature should be considered might include the initial move of traffic to ImageEngine or sites with unusually big- or user-generated images that may take time to process.
Note that the default behavior is that the origin will not be served if the request explicitly contains any of the following directives:
/m_in combination with w_ and h_
w_present with values less than the original image intrinsic height or width.
- This behavior can be overridden by selecting the “Apply to all images requests regardless of directives” option.
Set the maximum time allowed for ImageEngine to wait for a response from the origin server. The maximum allowed value is 120 seconds.
Usually, it is not recommended to change any of these settings. However, for specific cases, this section allows you to force a specific image format to always be served.
Selecting a "Preferred Output Format" will first try the preferred format and use that, if the device has support for it. If not, ImageEngine will fall back to the default behaviour by selecting the appropriate format.
Alternatively in Auto mode, you can specify which image formats should not be considered when automatically converting the image.
Custom Response Headers
If you need ImageEngine to return specific headers you can define them here. Typical use cases may be content security policies, referrer policies, or simply your own custom headers.
Any header added here will overwrite other headers with the same name. For example, if the origin server is returning x-my-header: true and the custom header x-my-header: false is added here, the browser will receive x-my-header: false.
Custom response headers may be handy when configuring CORS behavior.