How to customize Predictive Content Recommendation widgets

Business Case:

KPI to be measured

Bookmark this resource Follow

Ask a question

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

Predictive Content Recommendation (PCR) application offers two different embeddable widgets which can be used to suggest content to your contacts within your web pages. The embed code of such widgets is provided within the management console of each recommendation, in the Intelligence section of the Dashboard. The code can be simply copied and pasted in your pages to make it work. There are some available customization which will allow you to adapt the appearance and the behavior of the widgets. Let's take a look at the available parameters:

 

Embed parameters

 

Embed parameters common to all widgets

  • clientId ( string, mandatory): the domain name used to access THRON. Usually matches your company name.
  • appId ( string, mandatory): the id of the specific recommendation.
  • type ( string): the layout type of widget. Accepted values are: "wall", "list" or "none". If "none", no UI will be created, but methods and events will be exposed. "none" is useful when you want to create an entirely custom UI or if you want an easy access to recommended content. Default is: "none".
  • applyFallbackStrategy ( boolean, optional): this parameter allows you to configure the behavior of the recommendation widget when there are no available content to recommend. If "true" and no content is available, the widget will display the latest content published within the folder related to the specific recommendation. Default is: "true".
  • locales ( object, optional): Comma separated list of content locales. Default is the language of the browser, with fallback to "EN".  The object is in the form {content: "EN", interface: "EN"}. Where "content" is the language of the content information (title, description), while "interface" is the language of the widget's UI. You can use language codes included in the ISO639-1 standard. Default is: "EN"
  • ignoreUserBehavior ( string, optional): If "true", this parameter prevents the tracking of impressions and clicks of the content displayed. Default is: false.
  • itemTemplate ( string, optional): Parametric HTML Code for a single item in the widget. Provided HTML will be used into the UI. It is useful when you want a wall or a list widget but with a custom UI. In this HTML you can add some placeholders in the form:{{placeholder}}; and they will be automatically replaced with its related content information. All valid placeholders can be found in the section below.
  • skin ( string, optional): the name of the skin. this string is used to create main css classes, applied to main html elements. The css class is a result of a concatenation: "th-recommendation-widget-skin-{{skin}}". If you are building your custom UI and you want to avoid CSS conflicts with default properties, you should use this parameter.
  • thumbSize (widthXheight, optional): this param is used to calculate the size of the thumbUrl content attribute.

Content List parameters

  • autoplay ( boolean, optional): if "true" the list will automatically scroll without user's interaction. Default value is: false.
  • scrollSpeed ( number, optional): allows you to set the scroll speed (in ms) of the elements. Default is: 400.
  • autoplayTime ( number, optional): if "true", it will allow you to set the time (in ms) between scrolls. Default is: 3000.
  • slidesToScroll ( number, optional): allows you to set the number of elements to be scrolled; you can not set a number higher than the number of elements displayed by the widget. Default is: 1.
  • maxElements ( number, optional): allow you to set the maximum number of elements within the content list. Default and max is: 30.

Content Wall parameters

  • cellGutterX ( number, optional): allows you to configure the distance in pixels between the elements of the wall on the x-axis. Default is: 8.
  • cellGutterY ( number, optional): allows you to configure the distance in pixels between the elements of the wall on the y-axis. Default is: 8.

 

API

 

Methods

  • on: This method can be used to set a listener for widget's events. The "on" method receives an input parameter equal to the event name and the function to be executed (handler).
  • off: This method can be used to remove a listener for widget's events.
  • destroy: This method can be used to destroy a widget's instance.
  • getInfo: Returns a promise. When resolved, the promise will return an item. This item has two attributes "content" and "user" with all the relative information.

Example:

<script src="https://<clientId>-pcr.thron.com/pcr/embed/<clientId>/<appId>/bootstrap-min.js"></script>
<div id="<domId>" class="widget" style="height: 100%; width: 100%;"></div>
     let embedParams = {
        ...
    };
     let widget = THRONRecommendation("", embedParams);
     widget.destroy();

 

Events

  • ready: Fired when the widget is ready.

Example:

<script src="https://<clientId>-pcr.thron.com/pcr/embed/<clientId>/<appId>/bootstrap-min.js"></script>
<div id="<domId>" class="widget" style="height: 100%; width: 100%;"></div>
     let embedParams = {
        ...
    };
     let isReady = function(){
         console.log("READY");  
     };
     let widget = THRONRecommendation("", embedParams);
     widget.on('ready', isReady);


Customization info


Placeholders for itemTemplate parameter

All content attributes are valid placeholder.
You can get all content and its attributes through 'getInfo' method. Example:

let embedParams = {
        ...
    };
    let widget = THRONRecommendation("", embedParams);
    let promise = widget.getInfo();
    let oninfoReady = function(info){
        console.log('ALL CONTENT', info.content);
    };
    promise.then(oninfoReady);

Here some content attributes (that is valid as placeholder):

  • {{title}}: Content title
  • {{description}}: Content description
  • {{url}}: Content url. In the default UI it corresponds to the link to be opened when a user clicks on an item.
  • {{scores}}: A numeric value which express the accuracy of the recommendation. The higher this value, the more that content is considered interesting for the user.
  • {{contentType}}: Content type (IMAGE, VIDEO...)
  • {{dynThumbService}}: Generic content thumbnail url. 
  • {{thumbUrl}}: thumbnail url with H and W
  • {{id}}: Content ID

Additional placeholder for wall widget only:

  • {{classSort}}: A number between 1 and 3 calculated using content scores.The higher its value, the more that content is considered interesting for the user. This placeholder is used in the item template to create a parametric css class: th-recommendation-wall-item__{{classSort}}. This means that the item with th-recommendation-wall-item__0 will be bigger then th-recommendation-wall-item__1. Example:
    let templateWall = "<div class='th-recommendation-wall-item__{{classSort}} th-recommendation-wall-item wall-template'><div class='th-recommendation-lazy-bg poster'></div><div class='title'> Content title: {{title}}</div></div>";
    let recommendationWallParams = {
        appId: "<appId>",
        type: 'wall',
        clientId: "<clientId>",
        itemTemplate: templateWall
    };
    let recommendationWallWidget = THRONRecommendation("widget-wall", recommendationWallParams);


Lazy loading thumbnails

If you are building an item with a custom UI that contains a thumbnail, it may be useful to use
'th-recommendation-lazy-bg' as css class.
By adding that css class to the thumbnail container, the image will be loaded only when visible and with the correct size (it uses the container dimensions). Thus saving bandwidth and optimizing experience. The image will be added to the container as a background image.

Example:

let templateList = "<div class='item'><div class='th-recommendation-lazy-bg poster'></div><div class='title'> Content title: {{title}}</div></div>";
 let recommendationListParams = {
    appId: "<appId>",
    type: 'wall',
    clientId: "<clientId>",
    itemTemplate: templateList
 };
 let recommendationListWidget = THRONRecommendation("widget-list", recommendationListParams);
Was this article helpful?
2 out of 2 found this helpful

Have any question?

Open a ticket
Comments