How to embed images into your projects

Business Case:

KPI to be measured

Bookmark this resource Follow

Ask a question

Was this article helpful? 2 out of 2 found this helpful



In this article we are going to illustrate how to include images within your projects using THRON web services, without using THRON Player but preserving the tracking of users interactions. Moreover, we are going to see how, thanks to Real Time Image Editor application, you can generate image crops and resizes in order to have a different output starting from the same content, without creating any duplicate.


Request structure


The url of the request providing a THRON image is structured as follows:


When retrieving an image please remember that the highest width returned by the Real Time Image editor is 4096px (if the original image reaches this size).

For all other cases where you want to include the thumbnail of a content (not an image content type), the structure of the service is:





  • clientId (mandatory): is the domain name used to access THRON. Usually the company name.
  • contentId (mandatory): the unique identifier of the content for which you want to extract the image, can either be the xcontentId the prettyId or the externalId.
  • pkey (mandatory): must be a valid pkey for the specific image. To obtain a valid pkey for a specific set of content you must use a THRON Custom Application Manager as explained in this article.
  • divArea (mandatory): it is the desired dimension of the resulting image. If it is higher than the original image's dimension, no processing will be performed. If you want to get the highest thumbnail available you can set this parameter to "0x0".
  • prettyName (mandatory): the name to be used for the image for indexing purposes. You can put any name you want on this parameter, as long as it includes an extension, otherwise CMS libraries won't recognize it as an image asset. Use a name that is beneficial for your SEO strategy. Since the image might change in THRON over time, you are given the possibility to enter a custom name: because you don't necessarily want the URL of the image to change, thus preserving content indexing.
    THRON will not consider the extension, if the source image is a png, THRON will return a png.
  • rtieParams: all rtie parameters provided as query strings.
    Available rtie params are:
    • scalemode (optional): It represents the method used by the service to crop and resize the image. Available values are:
      • manual: (default value): is used to specify crop parameters, if no "cropmode" is provided, the image will be scaled to fit the requested dimension;
      • centered: it scales the image to fit the requested dimension, cropping borders if desired aspect ratio is different from the source image;
      • auto: this mode applies a smart cropping of the image by preserving the subject, regardless its position.
      • product: this mode is specific for product images which have some common caracteristics (e.g. uniform background color, focus on the only object present). The crop will always be made by removing the parts of the background in excess and centering the subject, giving more weight to elements that are not predominant.
    • cropmode (optional): It is used to define whether cropping will be performed with absolute coordinates or relative ones. Available values are: pixel; percent (default). Percent values always refer to the original size of the image.
    • cropx (optional): Starting point (distance from left border) of the cropping function. Default value is 0 (top left corner of the image).
    • cropy (optional): Starting point (distance from top border) of the cropping function. Default value is 0 (top left corner of the image).
    • cropw (optional): The width of the resulting cropped image before resize. The default value is the width of the image minus cropx. If this value is higher than the Width of the requested image, no resize will be performed.
    • croph (optional): The height of the resulting cropped image before resize. The default value is the height of the image minus cropy. If this value is higher than the Height of the requested image, no resize will be performed.
    • quality (optional): the quality parameter enables you to optimize the quality of an image to obtain the right quality-weight balance for web usage. Image quality vary on a scale from 5 to 100 (in THRON, the default quality level is 90). In addition, THRON has introduced a series of quality pre-sets that enables you to choose the perfect quality-size combination for an image according to the specific situation. You have 6 quality pre-sets at your disposal (3 are static, 3 are dynamic). In particular, dynamic quality pre-sets do this operation automatically: they analyze and compare the original image and its low-quality version and choose the ideal quality value on the basis of their similarity. Allowed values are: 
      • high: static values; to use if you prefer excellent image quality at the expense of its size;
      • medium: static values; to use to obtain the a balance between quality and weight;
      • low: static values; to use when lower weight is preferred over quality;
      • auto-high: dynamic values; to use if you prefer excellent image quality at the expense of its size;
      • auto-medium: dynamic values; to use to obtain the a balance between quality and weight;
      • auto-low: dynamic values, to use when lower weight is preferred over quality.
        In case you need to publish high-quality images or images containing texts, we suggest using auto-high/high presets instead of webp format. 
    • adjustcrop (optional): when the aspect ratio of the cut and the divArea are different, this parameter defines the rule to be adopted to handle the output. This parameter is mutually exclusive with fillcolor. Available values are:
      • no (default): no changes are applied to the crop area, therefore the output image might have a different aspect ratio than the divArea;
      • extend: the crop area is potentially expanded (so it might return a slightly "larger" image) in order to guarantee that the output has an aspect ratio identical to the divArea;
      • reduce: the crop area is reduced (so it might return a "smaller" image) in order to guarantee that the output has an aspect ratio identical to the divArea.
    • fill (optional): when the divArea is larger than the source image (or selected crop), this parameter forces the scaling of the output in order to fill the divArea (it ensures that at least one of the two dimensions is exactly as specified In the divArea). Available values are:
      • no (default): do not process the input;
      • zoom: scale the image but do not fill it with colored bands in case of different aspect ratio.
    • fillcolor (optional): when the aspect ratio of the divArea is different than the source image, this parameter extends the output through a specific color. It ensures that the output size is exactly as large as the divArea. This parameter is mutually exclusive with adjustcrop. In case of PNG or GIF images with transparency, the fillcolor parameter indicates the color with which the transparent area will be replaced in JPG conversion. The format parameter can heavily influence the performance because it allows a lot of weight reduction. If you convert an image from PNG to JPEG you will have a considerable increase in performance because of the bandwidth used for downloading the image.Available values are:
      • no (default): do not alter the size of the image;
      • rgba r,g,b,a: with r,g,b from 0 to 255 and a from 0 to 1, indicating respectively the levels of red, yellow, blue and alpha. E.g.: fillcolor=rgba:255,100,0
    • format (optional): the format parameter enables you to change the image output format in order to deliver the best image format for web usage. Available values are:
      • no (default): keep the output format of image conversion (PNG or JPEG); for example, if you upload a TIFF image, using “no” the RTIE will deliver a JPEG image;
      • auto: this value enables you to automatically set the optimal format for the image. Setting “format=auto”, RTIE will first check if the browser in usage supports the WEBP format:
            • In case the browser supports this format, it will automatically convert the original image into a WEBP one.
            • In case the browser does not support this format, RTIE will check if the original image present a transparency. If the image present a transparency, the system will deliver a PNG; in case the image does not present a transparency, the system will automatically convert it into a JPEG image in order to make it lighter.  
      • JPEG: JPEG images tends to be lighter than PNG ones. For this reason, JPEG format is the best choice in case you need to convert a PNG image that has not a transparency. If you convert a PNG image that has a transparency to a JPEG one, the transparency will be converted to white, unless you manually set another color for the background through the fillcolor parameter;
      • PNG: a PNG image is much more weighter than a JPEG one. Note that converting a JPEG image into a PNG one only involves an increase in weight, without increasing its quality;
      • WEBP: this format is ideal for web image optimization. Be aware that, in some case, images can come in low quality due to chroma subsampling stuck at 4:2:0;
    • enhance (optional): this parameter allows you to adjust the color, brightness, contrast and sharpness of the image, using the form enhance=brightness:100,contrast:100,sharpness:100,color:100. Each parameter must be provided with an integer between 0 and 200.
    • dpr (optional): the device pixel ratio is used to display images at the correct pixel density on a variety of devices such as Apple Retina displays and Android devices, or to provide a proper resolution when integrating a zoom function over the image. dpr must be provided as an integer between 1 and 1000. Default is 100.[/dropdown]




This web service enables content indexing by search engines' crawlers. In order to facilitate the retrieval of the content via search engines, the embeds must be enriched with specific html tags. All the information on how to include html tags to enhance content indexing can be found in this article.




Thanks to THRON tracking library, you can track users interactions with the image even when you are not using THRON Player to deliver it.

The first thing to do is to include the library in the <head> section of your webiste, using the following form:

<script id="ta_bootstrapper" src="<clientId>"></script>

THRON Tracking Library exposes a method which can be used to automatically track different users interactions with images included into the web page by simply using an inline css rule.
This means that on your webpage you will have to include a specific class to any <img> tag you want to track (make sure the asset is delivered by THRON).

This class is made of two elements: prefix and event, in the form:

<img class="tci_impression_load_click" src=”//<clientId><clientId>/<contentId>/<pkey>/std/<divArea>/<prettyName>?<rtieParams>” />

Where tci is the default prefix used by the library while available events are:

  • impression: the event is registered when at least 1/3 of the image is visible on screen.
  • load: the event is registred when the user spent 3 seconds with at least 1/3 of the image visible on screen.
  • click: the event is registered when a user clicks on the image to trigger some action.

You can simply omit any of the event from the class if you don’t want it to be tracked.


Use cases

[dropdown:Automatic crop & resize preserving image subject]If you wish to embed an image into a div which has a smaller size than the original image, the best way to do it is to use the "auto" mode of the Real Time Image Editor. Just set the div area of the image at your will and set the scale mode to "auto". The service will return you the perfect image to be fitted in the div.


Here's an example:


This is the original image which is a 1920x1080, with an a/r of 16:9:





Let's suppose i have to include it in a 200x200 <div> which has an a/r of 1:1 and a smaller size, but i want to preserve the image subject. Using the auto scalemode, this is what I'm going to obtain:




The url of the image has the following structure:



[dropdown: Optimizing Image payload through Quality preset]

All THRON quality presets (including low/auto-low) preserve image quality while saving size. In this way, users are not able to perceive any decrease in quality. Below is a practical example where three images with the three quality presets are embeddable:


Image without any quality parameter:



Image with quality=auto-high:



Image with quality=auto-medium:



Image with quality=auto-low:



As you can see, while maintaining the quality of display, analyzing the size of resources downloaded from the browser, you can see a significant decrease in weight of the images compared to the one where the parameter is not used.

Below are the file size values of the resources downloaded in comparison with the original image weight of 37KB:

  • auto-high: 35.32 KB - 4% saving;
  • auto-medium: 23.3 KB - 36% saving;
  • auto-low: 19.3 KB - 47% savings.



[dropdown:Fitting an image into a specific <div>]

If you wish to fit an image into a specific <div>, you could either do that by cropping and resizing it in order to make a specific detail of the image fit the space properly or you might want to just center the image into that div. In the first case you can use the "manual" scale mode of the getThumbnail web service; in the second case you use the "centered" scale mode.

The "manual" mode can be easily exploited in the GUI assistant which can be found within the Shareboard of your IMAGE content, under the "Cutom Thumbnail" sharing type.


Here is an example:



This is the div:




This is what i get with a manual crop:



This is what i get with the centered scale mode:



This is the url structure when using the "manual" scale mode:



This is the url structure when using the "centered" scale mode:


[/dropdown][dropdown:Scale the image to a smaller resolution]If you wish to preserve the original image in its integrity but simply scale it to a smaller resolution you can simply edit the divArea within the url, without providing any additional parameter. Just set the desired height or width, and the other dimension will adapt accordingly.

This is an example:



The url will be structured as follows:



[dropdown: Widescreen: use the selected crop to fit the entire divArea]

Let's suppose you want to make a specific crop of the image and make it fit the whole divArea, even if the aspect ratios are different, you will have a situation like this one:

This is the original image:



This is the crop i want to make:



And let's suppose i need to place it into a square container. In this case i will have to use the "extend" parameter in order to adjust the crop, selecting a bigger portion of the crop (if needed), in order to fit the whole divArea.

The url of the request will be structured as follows:


which can be put in a square div like this one:




With this result:



[dropdown: Letterbox: Fit the selected crop into the divArea, showing background bars if needed]

Let's suppose you want to fit a specific crop into a divArea with different aspect ratio, but without "extending" the cropped section; in this case it might be necessary to show some background bars if the image is fitted into a bigger divArea. If this is the case you will have to use the "fill" parameter, and the color of the background bars can be customized through the "fillcolor" parameter, like in this example:

This is the original image:



This is the crop i want to make:



And let's suppose it has to be fitted into a square div: 400x400 pixels.

The url of the request will be structured as follows:


Obtaining the following result (in the example we have set a red background > rgba:252,13,13,255):


[/dropdown][dropdown:Placing a product image within a product sheet or a catalogue]

If you need to place a product image within a specific page such as a product sheet or a catalog page, and this image should have a neutral background that can be sacrificed to give more evidence to the product represented, you can use the product scale mode.

This mode automatically cuts off the excess portion of the background while keeping the entire outline of the product represented within the visible area, increasing its visibility.

Here is an example: the left image has been inserted without any scalemode, and as you can see there is a portion of the background that sacrifices space useful to increase the visibility of the product, in the right pane we have included instead the scalemode product, automatically cutting out the portion of the background in excess and making the product more visible.



The url of the request is structured as follows:



[/dropdown][dropdown:Embedding an animated GIF ]

If you want to preserve the animation of a gif, you should upload the content as a DOCUMENT, and use the public/document web service to deliver the animated image.




[/dropdown][dropdown:Manipulating an image]

You can tailor image transformations based on conditional parameters or the viewing context to deliver the most appropriate version to users. The parameters that can be used to manipulate the image are brightness, contrast, sharpness, color.

For example you can include a black and white image by setting the color parameter to 0:

This is the original image:



This is the black and white version of the same image:



The url of the request is structured as follows:




[/dropdown][dropdown:Optimize image delivery on retina displays]

For perfect image rendition on high pixel density screens, such as the retina screens of Apple devices, you can use the dpr parameter.

For example, given the same container, on the left you find the image included with the default dpr, on the right an image that has a density of pixels twice as high and therefore will be rendered better on retina screens.

Note: You are not going to see any difference between the two images unless you are using a retina display.





Images have been included with the following url:




[/dropdown][dropdown:Change the background color of a transparent image]If an image with a transparent background has been uploaded to THRON, it will be possible to change the background colour of the image while it is being delivered. To do this, use the fillcolor parameter and provide the background colour code in rgba format. The resulting image will be a jpg with the background colour selected.




Hint: set the proper image according to device resolution


According to device's dpi it might be convenient to embed different resolutions of the image; the browser will automatically choose the most appropriate resolution according to the device in use. In order to do so you can use the "srcset" attribute of the <img> tag. This attribute allows you to define various image resources and “hints” the user agent to determine the most appropriate image source to display. Given a set of image resources, the user agent has the option of either following or overriding the author’s declarations to optimize the user experience, the choice is based on different criteria such as:

  • display density (dpi)
  • connection type
  • user preferences (bandwidth/data saving)
  • other criteria that might change according to the specific browser

The use case here is: I want the same image to be displayed across all devices, but I want to display it in a higher resolution on devices which can support it.


Here is an example:


<img src="//<clientId><clientId>/<contentId>/<pkey>/400x400/<prettyName>.png?<rtieParams>" srcset="//<clientId><clientId>/<contentId>/<pkey>/400x400/<prettyName>.png?<rtieParams>1x, //<clientId><clientId>/<contentId>/<pkey>/800x800/<prettyName>.png?<rtieParams>2x, //<clientId><clientId>/<contentId>/<pkey>/1200x1200/<prettyName>.png?<rtieParams>3x, //<clientId><clientId>/<contentId>/<pkey>/1600x1600/<prettyName>.png?<rtieParams>4x" />


NOTE: Internet Explorer and Edge browsers currently do not support the srcset attribute.

Further reference on srcset attribute can be found in this article.


Was this article helpful?
2 out of 2 found this helpful

Have any question?

Open a ticket