How to embed images into your projects

How to embed images into your projects

Introduction

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:

//[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[contentId]/[pkey]/std/[divArea]/[prettyName]?[rtieParams]

where:

  • 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 or the prettyId.
  • pkey (mandatory): must be a valid pkey for the specific image.
  • 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.
  • rtieParams: all rtie parameters provided as query strings. Such parameters will be ignored if the Real Time Image Editor application has not be installed in your Platform. Available rtie params 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 will work only if "Real-time Image Editor" (RTIE) application has been purchased. It applies a smart cropping of the image by preserving the subject, regardless its position. An interactive demo of how the application works can be found here. If auto mode is requested but the application has not been purchased, the service will return the image centered according to the requested resolution.
    • scalemode (optional): It represents the method used by the service to crop and resize the image. Available values are:
    • 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 left 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 of the resulting image. Available values are: [0-100]. Default value is 90.
  • 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,a from 0 to 255 indicating respectively the levels of red, yellow, blue and alpha.
  • format (optional): the desired format for the resulting image. Available values are:
    • auto (default): if image have transparency keep original format, else convert to JPEG ;
    • JPEG;
    • WEBP (currently supported by Chrome only).
  • 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.

 

SEO

All the information on how to include html tags to enhance content indexing can be found in this article.

 

Tracking

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]-cdn.thron.com/shared/plugins/tracking/current/bootstrapper-min.js"></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]-cdn.thron.com/delivery/public/image/[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:

//[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[contentId]/[pkey]/std/[divArea]/[prettyName]?scalemode=auto&quality=100

[/dropdown][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:

 

400x400

 

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:

//[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[contentId]/[pkey]/std/[divArea]/[prettyName]?quality=100&cropw=[cropw]&croph=[croph]&cropx=[cropx]cropy=[cropy]&cropmode=[pixel]

 

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

//[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[contentId]/[pkey]/std/[divArea]/[prettyName]?quality=100&scalemode=centered

[/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:

//[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[contentId]/[pkey]/std/[divArea]/[prettyName]

[/dropdown]

[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:

Schermata_2017-07-05_alle_11.59.11.png

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:

http://[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[xcontentId]/[pkey]/std/[divArea]/[prettyName]?scalemode=manual&cropmode=pixel&adjustcrop=extend&cropx=[cropx]&cropy=[cropy]&cropw=[cropw]&croph=[croph]

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

400x400

With this result:

[/dropdown]

[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:

Schermata_2017-07-05_alle_12.27.59.png

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:

http://[clientId]-cdn.thron.com/delivery/public/image/[clientId]/[xcontentId]/[pkey]/std/[divArea]/[prettyName]?scalemode=manual&cropmode=pixel&cropx=[cropx]&cropy=[cropy]&cropw=[cropw]&croph=[croph]&fillcolor=[rgba]&fill=zoom

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

[/dropdown]

Hint: set the proper image according to device resolution

According to device's dpi you might want 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.

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]-view.thron.com/api/xcontents/resources/delivery/getThumbnail/[clientId]/400x400/[xcontentId].jpg"
     srcset="//[clientId]-view.thron.com/api/xcontents/resources/delivery/getThumbnail/[clientId]/400x400/[xcontentId].jpg 1x,
     //[clientId]-view.thron.com/api/xcontents/resources/delivery/getThumbnail/[clientId]/800x800/[xcontentId].jpg 2x,
     //[clientId]-view.thron.com/api/xcontents/resources/delivery/getThumbnail/[clientId]/1200x1200/[xcontentId].jpg 3x,
     //[clientId]-view.thron.com/api/xcontents/resources/delivery/getThumbnail/[clientId]/1600x1600/[xcontentId].jpg 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?
1 out of 1 found this helpful

Have more questions?

SUBMIT A REQUEST

Hai altre domande?

INOLTRA UNA RICHIESTA

Comments