We’ve migrated our documentation to a new site, which means some URLs have changed.
Audience
Audience
Breadcrumbs

Piano Content Recommendation Tutorial

Introduction

This tutorial is the first in a series of three that covers Cxense Content Recommendation. The two other ones are:

  • Cxense Content Recommendation CSS Style Tutorial

  • Cxense Content Recommendation Config Tutorial  

Content Recommendation is the science of knowing what the user, as well as all the other visitors to the site, is currently reading as well as what they have been reading in the past, and the art of acting upon that data in such a way that we can stimulate the user to spend more time and to consume more content at the site.

There are 3 questions we need to answers before deploying a Cxense Content Recommendation widget:

  • Where do we place the widget?

  • What is the widget to look like?

  • What type of recommendation is the widget to display?

To come up with the best answers to these 3 questions, is, as we will learn in this tutorial, not an exact science. This tutorial will however provide us with plenty of guidance. But before we get there, there is another question we will be answering first, and that question does indeed have an straight forward technical answer. And the question is: How do we create a content recommendation widget?

How do we Create a Content Recommendation Widget?

image-20211217-125718.png


The figure above shows how a Content Recommendation widget is created, deployed and used. In blue step 1 an operator uses the Cxense Portal to create a widget with its 3 sub components, a content config, a javaScript template and a CSS style sheet. In blue step 2 the resulting widget tag is obtained and deployed on the site's web pages. When a user then opens a page (green step 1), the execution of the tag will cause a request for content recommendations to be sent and an iframe with matching recommendations to be returned (green step 2).

Prerequisites

These are the prerequisites for being able to create and deploy a content recommendation:

  • Create a site group (if it does not already exists)

  • Add a site to site group (if it does not already exist)

  • Obtain write access for the site site group

  • While not necessary for creating a training widget, for well performing production widgets:

    • the site must be whitelisted

    • meta tags must be added if current data quality deems it necessary

Creation and Deployment Procedure

image-20211217-125734.png


  1. Create a new widget: Follow the red Create Widget menu option route in the figure above. When you have the form open, fill out the Description field and select the Site where you will show the recommendation and set the Size (the number of recommendations to be shown). Leave the rest blank for now and click the Create button at the bottom.

  2. Add the default content configuration to the widget: Click the Contents tab and then the Create new content configuration button. When the form appears, fill in the Description field and then click the Create button without doing any changes to the form. Then find back to the widget form and there select the just created content from the Content drop down box and then click Save changes.

  3. Add the default template to the widget: Click the Templates tab and then the Create new template configuration button. When the form appears, fill in the Description field and then click the Create button without doing any changes to the form. Then find back to the widget form and there select the just created template from the Template drop down box and then click Save changes.

  4. Add the default style sheet to the widget: Click the Styles tab and then the Create new style configuration button. When the form appears, fill in theDescription field and then click the Create button without doing any changes to the form. Then find back to the widget form and there select the just created style from the Style drop down box and then click Save changes.

  5. Add the widget to a web page: Click the Widgets tab and go back to the widget form. Click the Script tag button. Cut and past the javascript code that appears in the pop up window into a web page of yours as shown below (click on image to enlarge) and save the file to your computer as test.html.

    image-20211217-125755.png

  6. See the recommendations in your browser: Open the test.html web page in a browser and voila, you have the recommendations shown below appearing in your browser window.

    image-20211217-125803.png


  7. Replace the default content configuration with a meaningful one: Ok, we must admit, these were not very useful recommendations as the very same hard coded recommendations will be shown every single time and they don't even have anything to do with neither the article on the page nor with the content of pages the user have visited before. Ok, we will fix that by replacing the default content configuration we have been using with the one below. Just make sure to insert your site id on line 4 before doing so.

    {
  "type": "recs",
  "siteIds": [
    "<ADD YOUR SITE ID HERE>"
  ],
  "matchingMode": {
    "trend": {
      "weight": 10,
      "period": 86400
    },
    "behavioral": {
      "weight": 5
    },
	"contextual": {        
	  "weight": 5
	} 
  },
  "resultFields": [
    "url",
    "title",
    "dominantthumbnail",
    "dominantthumbnaildimensions"
  ],
  "maxAge": 10080,
  "query": "query(dominantimagedimensions:\"*\")"
}

    The configuration above will recommend a combination of content that has been popular (matching mode set to trend) during the last 24 hours (period set to 86400 seconds) with content similar to what the user has read before (matching mode set to behavioral) and to similar content of the current page (matching mode set to contextual). None of the recommendation will contain articles older than 7 days (maxAge set to 10080 minutes) and only articles with an image (dominantimagedimensions) will be recommended. We also made sure that resultFields contain all the fields our template code make references to. Here we see an example of the result after having updated to the configuration above:

image-20211217-125835.png

Where do we Place a Content Recommendation Widget?

To the right we see a typical on-line news article. It has a headline, a large eye-catching photo high up on the page, and then the news story itself. Trailing it we see the more and more commonly occurring commentary area where readers can give their opinion on the story and/or its topic.

We have decorated the news story with colored content recommendation placeholder boxes. These are areas where one potentially could place content recommendation and we will in the following go through each area and discuss it usefulness in this respect and what types of recommendations that ought to be placed there.

  • Distraction and redirection area - At the top of the news article one finds the distraction and redirection area. This is an area one normally should avoid as it often distracts the readers and stops them from reading the article itself or seeing any ads lower down on the page. However, there are types of readers one purposley wants to distract to redirect them to other content. An example of this is visitors from Facebook that otherwise often would just bounce back. In this case the recommendations should then also be tailored to the group in question and not appear at all for any other type of visitors.

  • Bored readers area - To the right around half-way down the article is where readers that did not find the article all too interesting start loosing concentration and should be distracted. Since they might not have found the article all too interesting this would be a good place for recommending something else than what the article is about. For instance, one could recommend something that is trending in the news right now or something that the reader has shown interest for in the past.

  • Interested reader area - The area immediately below the article will only be reached by readers who had enough interest in the article to read it to the end. These readers are likely to want to read more about the very same topic. Hence, recommendations in this area should to a large degree recommend more of the same that what the article was about.

  • Graveyard area - The graveyard area is where recommendations go to die. This applies to any area below the article that is not immediately following it. To use this area is to set one self up for failure. Hardly any reader will ever see what you place in this area and you are almost guaranteed an CTR close to zero.

How to actually implement the area type to content type matching described above is done via the content config and is covered in this section of the second tutorial,

Summing it all up:

  • End articles with recommendation for similar content (ref. interested reader area)

  • Have an alternative offering for readers that loose interest midway through the article (ref. bored readers area)

  • Don't let anything come between the end of the article and any of our recommendations (ref. the graveyard area)

  • Don't distract the user unless that is the exact intention (ref. the distraction and redirection area)

What should a Content Recommendation Look like?

Relevant content placed within view of the reader will still not lead to more CTR if the recommendation's layout does not stimulate the readers to click on it. The most important rule of thumb is that one include an image, and the larger the image the better. The text should be short and strengthen the message of the image. News article headlines combined with the article's main image is normally the way to go. Below we see two layout improvement examples with the old layout to the left and the improved layout to the right. The first example is from a non-news site that recommends information about movies, the latter is from a regular news site.


image-20211217-125907.png

The recommendations from before the improvements look awkward both when they have a short title only (the case above) or when they have both title and body teaser (see below). In both cases it is relatively easy to see why a large image combined with the title only is likely to stimulate more clicks than the versions to the left. 

Summing it all up:

  • Size matters, a big picture is better than a small picture, and a small picture is better than no picture

  • Make the text short and simple, just enough to get the idea what it is about across (the title is normally a winner)

Go to Cxense Content Recommendation CSS Style Tutorial to learn the details on CSS styling.

What Type of Recommendation are we to Display?

Below we see a list of the configuration option we have when it comes to deciding what type of recommendations a widget is to display.

  • trend - articles popular right now

  • aiTrendBehavioral - articles popular right now, ranked by the user past interests (AI embeddings-based)

  • contextual - articles similar to the article the user is currently reading

  • aiContextual - articles similar to the article the user is currently reading (AI embeddings-based)

  • aiContextualBehavioral - articles similar to the article the user is currently reading, ranked by the user past interests (AI embeddings-based)

  • behavioral - articles similar to those the user has read in the past

  • aiBehavioral - articles similar to the user past interests (AI embeddings-based)

  • collabctx - articles read by others that have also read article the user is currently reading

  • collabusr - articles read by others with similar interests as the current user

For learning how to set these as well as many other display related settings, go to Cxense Content Recommendation Config Tutorial.

Last updated: