Recommendation Rules Documentation

Introduction

This document describes how to use the dashboard to create rules that govern the personalized recommendation widgets.

Definitions

Rule: A predefined instruction with the purpose to influence the processing or output of the recommendation engine in a specific manner.

Rule Group: A set of one or more Rules grouped together. A Rule Group can be assigned to many Widgets. Each Widget can have up to 1 Rule Group only.  

Rule Kind: The aspect or property that the Rule will administer. Each Rule must specify one Rule Kind from the following list as defined below “Category, PageType, CustomField, Article, Thumbnail, Language, FilterPeriod”

Category: This is the Category of an article as suggested by Magnet. Currently the value of this can be: “General, Business, Law Enforcement, Entertainment, Health, Politics, Science, Sports, Technology”

PageType: The type of the content. Currently the value of this can be: “Article, Video, Gallery, Image”

CustomField: A custom field property that must also be present on the webpage metadata

Article: A specific article or content that can be identified by an Article UID (the identifier property on the webpage)

Thumbnail: A (specific) picture on the webpage.

Language: The language of the webpage

FilterPeriod: The period to compare against the Last Update Date of the webpage

Rule Type: Each rule must have one of the following types as defined below “Show Only, Exclude, Push, Bias Plus, Bias Minus, Dynamic Show Only”.

Show Only:Only recommend content that adheres to a rule

Exclude: Omit from the recommendation output the content that adheres to a rule

Push: If possible,make sure the recommendation output contains a content that adheres to a rule

Bias Plus:bias positively the score of the content that adheres to a rule, which gives them a better chance to be recommended if they match the user profile

Bias Minus:bias negatively the score of the content that adheres to a rule, which gives them a lower chance to be recommended if they match the user profile

Dynamic Show Only: Only recommend content that adheres to a rule that is Dynamic in nature (i.e. follows some input from the webpage as opposed to being predetermined).

Valid: Each Rule has a lifetime with an upper and lower bound that dictates when it is valid and will be enforced.

Recommendation Rules on Dashboard

You can find the recommendation rules form by clicking on the “Widget” tab on the left panel, and then clicking on the “Recom Rules” button on the bottom strip.

 

Recom Rules form

On this page you will have the ability to

• Create Rule Groups
• Create Rules for each Rule Group
• Assign Rule Groups to Widgets

In the above picture, the set of buttons on the top controls the Rule Groups, while the buttons under the “Rules List” title control individual Rules for each Rule Group.

Whenever a Rule Group is selected from the left grid, the information on the right will update to reflect that Rule Group and its list of Rules.

Rules Group

To create a new Rule Group press the “New” button on the top left, enter the new Group Name in the pop up, and press Submit.               

 

Once the Rule Group is created, you mustselect it from the left grid in order to start adding Rules to it.

Note that the Rule Group name can be edited using the “Edit” button and of course deleted using the “Delete” button (which will also delete all underlying rules) found at the top of the form.

Rules

To create a new Rule simply press the “New” button found under the section titled “Rules List”. The following pop up will appear

Each rule must have a “Rule Kind” and “Rule Type” as defined in the definition section above. For each Rule kind different Rule Type options are available and different fields will be required.

All rules can have a validity period.

Add Category Rule

A Category Rule influences the Recommendation algorithm based on the Category of the contentas suggested by Magnet.

As shown in the above picture, the “Rule type” and the “Category” fields must be specified.

The “Rule Types” field can be selectedto “Show Only”, “Exclude” or “Push” a specific category.

The “Category” field must be set with content category desired. Currently the value of this can be: “General, Business, Law Enforcement, Entertainment, Health, Politics, Science, Sports, Technology”.

Fill “Valid” with the start date and expiry date of the rule.

Example:

In order to exclude from the recommendation’s output all the content that are of Category “Sports”, and push content of Category “Business”,two such Category Rules must be added to this Rule Group. One with the Rule Type set to “Exclude” and the Category set to “Sports”, and one with the Rule Type set to “Push” with Category “Business”.

Add PageType Rule

A PageType Rule influences the Recommendation algorithm based on the type of the content.

As shown in the below picture, the “Rule Type” and the “Page Type” fields must be specified.

 

The “Rule Type” field can be selected to “Show Only”, “Exclude” or “Push” content that of a specific type.

The “Page Type” field must be set with content page type desired. Currently the value of this can be: “Article, Video, Gallery, Image”.

Fill “Valid” with the start date and expiry date of the rule.

Example:

In order to recommend articles only and omit everything else (videos, images, and galleries), one PageType Rule must be added to this Rule Group. The “Rule Type” of that rule must be set to “Show Only” and the “Page Type” set to “Article”.

Add Custom Field Rule

A CustomField Rule influences the Recommendation algorithm based on custom fields set on the webpage’s metadata. These custom fields would be recognized and processed by Magnet during the crawling stage (on webpage addition or update).

As shown in the below picture, the “Rule Type” and the “Page Type” fields must be specified, along with the Custom Field Name and Value.

The “Rule Type” field can be selected to “Show Only”, “Exclude”, “Push”, “Bias Plus”, “Bias Minus”, or “Dynamic Show Only” content that has a specific Custom Field name and value set on the webpage.

The “Field Name” field must be set with the Custom Field name desired. The name must be written exactly the same as on the webpage.

The “Field Value” field must be set with the Custom Field value desired. The value must be written exactly the same as on the webpage.

Fill “Valid” with the start date and expiry date of the rule.

Example:

In order to only show recommended content that have the Custom Field name “Section” and either the value “Stocks” or the value “Market”, two CustomField Rules must be added to this Rule Group. The “Rule Type” of both rules must be set to “Show Only”, and the “FieldName” of both rules must be set to “Section”, while one rule will have the “Field Value” set to “Stocks” and the other to “Market”.

Please make sure that the webpages include these custom fields as well, otherwise the recommendation widget will not return any result in this case.

Add Article Rule

An Article Rule influences the Recommendation algorithm based on one specific article.

As shown in the below picture, the “Rule Type” and the “Article UID” fields must be specified.

 

The “Rule Type” field can be selected to “Exclude”, “Push”, “Bias Plus”, or “Bias Minus” one specific article.

The “Article UID” field must be set with the page identifier of the content in question. The content can be of any Page Type as long as an identifier is set on its webpage.

Fill “Valid” with the start date and expiry date of the rule.

Example:

If there are 2 specific webpages that needs to be never shown in the recommendation output and 5 other specific webpages that the website owner wishes for the users to see, then 7 Article Rules must be added to this Rule Group. Two rules with “Rule Type” set to “Exclude” and the “Article UID” set to the identifiers of those 2 specific webpages. Five rules with “Rule Type” set to “Push” and the “Article UID” set to the identifiers of those 5 specific webpages.

Note that the 5 webpages to be pushed won’t be shown at the same time on the recommendation widget and on every page load. Depending on how many articles the widget is set to show, some slots in that widget will show different articles from the list of articles to be pushed. Every page load will refresh the selection.

Add Thumbnail Rule

A Thumbnail Rule influences the Recommendation algorithm based on the availability of a thumbnail (or picture) with the content. This rule is usually created to make sure the recommendation widget contains content with an appealing thumbnail for better click through rate.

As shown in the below pictures, there are two ways to set a Thumbnail Rule. Either to “Show Only” content that have a thumbnail, or to “Exclude” content that have a specific thumbnail (usually the default picture). In the latter case, a Picture URL must be specified.

 

Fill “Valid” with the start date and expiry date of the rule.

Add Language Rule

A Language Rule influences the Recommendation algorithm based on the language of the content. This rule is useful for websites that publish content in more than one language.

As shown in the below picture, the “Rule Type” and the “Language” fields must be specified.

 

The “Rule Type” field can be selected to “Exclude”, “Show Only”, or “Dynamic Show Only” content that have a specific language. The latter means that the language of the articles to be recommended will be selected/filtered based on the language of the webpage that currently holds the widget.

The “Language” field must be set with language desired by selecting it from the dropdown menu.

Fill “Valid” with the start date and expiry date of the rule.

Example:

If a website has content in three languages “English”, “French”, and “Spanish” and the owner of the website wants the recommendation widget to always recommend articles in English* but also recommend articles in either* “French” or “Spanish” depending on the language of the current content being read, then two Language Rules must be added. One “Show Only” Rule with the “Language” field set to “English”, and one “Dynamic Show Only” Rule.

* if any is available and matches the reader’s profile.

Add FilterPeriod Rule

A FilterPeriod Rule influences the Recommendation algorithm based on the Last Update Date of the content.

As shown in the below picture, the “Rule Type” and the “Number of days” fields must be specified.

 

The “Rule Type” field can be selected to “Exclude” or “Show Only” content that have been added or updated in the past as specified in the “Number of Days” field.

The “Number of Days” field must be set with thenumber of days to compare against. This can be an integer or a decimal. For example, one valid value can be “2.5” which means 2 days an a half from the time of recommendation.

Fill “Valid” with the start date and expiry date of the rule.

Example:

In order to recommend articles that were created or updated in the past two weeks but not today, two FilterPeriod Rules must be added. One with Rule Type set to “Show Only” and Number of days set to 14. The second with Rule Type set to “Exclude” and Number of days set 1.

The widget will then look at the Last Update Date of the recommended content, if it was created or updated 14 days from the time of recommendation but not 1 day from the time of the recommendation, that content is allowed to be displayed in the widget.

Assign Rule Groups to Widgets

Whenever the Rule Group is populated with the required Rules it must be assigned to a specific widget for the rules to take effect as intended.

Accordingly, select the designated Rule Group from the grid on the left, and then click on the “Assign to Widget” button.

The available recommendation widgets will then be listed in a popup as per the below picture.

In case the list is empty, it means that no recommendation widgets have been created yet. Otherwise, it will list all the widgets with information on which Widget ID is assigned to which Rule Group.

One Widget can be assigned to up to one Rule Group. On the other hand, a Rule Group can be assigned to many widgets.To assign a Rule Group to a widget simply click the “assign” link on the last column for the designated widget id. To unassign, click the “unassign” link.

Example

As an example, here are some imaginary requirements, and the corresponding list of Rules that needs to be created to achieve them.

• Only show articles with Thumbnails
• Only show articles that are 10 days old
• Only Show articles that are English and that correspond with the language of the webpage currently being read.
• Exclude content that are of Category type “Politics”
• Push content of Category type “Sports” and “Entertainment”
• Bias positively articles with custom field“Author = Jane Doe” and Bias negatively the ones with custom field “Author = John Doe”.
• Push Videosonly in April 2018