Refinements

Refinements are added to apply filters to the returned recommendations. It is done for number of reasons such as filtering down the recommendation set to match a promotional landing page or matching the result set as a user navigates using a guided navigation.

If you use more than one refinement, the values are ANDed. For example:

Copy 
R3_COMMON.addRefinement('myVar', 'A');
R3_COMMON.addRefinement('myVar', 'C');

This will filter out everything but the items that had myVar set to A AND C.

IMPORTANT: Be careful when adding refinements. Filters are applied to a smaller set of recommended items, not to the entire catalog. Over filtering can prevent any recommendations from appearing.

If you plan to add more than one refinement on a page, please make your Algonomy team aware.

JavaScript Integration

How to make this code work for you

  1. Ask your Algonomy technical contact to enable Refinements for your site.

  2. Create the integration code on each of the pages on your site, following the HTML integration and JSON integration guides.

  3. Add this function to your integration code:

Function

Requirement

R3_COMMON.addRefinement('ATTRIBUTE_NAME', 'VALUE');

Replace ATTRIBUTE_NAME with the name of the product attribute you wish to use to filter products.

Replace VALUE with the value that the products must match to be recommended.

Sample Code

Call addRefinement() in the Primary Code Block.

HTML

Copy 
<!-- Place code inside the <body> element as close to the top as possible -->
<script src="//media.richrelevance.com/rrserver/js/1.2/p13n.js"></script>
<script charset="utf-8" type="text/javascript">
  var R3_COMMON = new r3_common();
  R3_COMMON.setApiKey('abcd5432e1');
  R3_COMMON.setBaseUrl(window.location.protocol+'//integration.richrelevance.com/rrserver/');
  R3_COMMON.setClickthruServer(window.location.protocol+"//"+window.location.host);
  R3_COMMON.setSessionId('6B4D397B');
  R3_COMMON.setUserId('1');  // if exists, set it; if not, set it as session ID
  
  // here's an example requesting recommendations for 1 page area
  R3_COMMON.addPlacementType('home_page.rr1');
    
  var R3_HOME = new r3_home();
 
  //Show only blue products.
  R3_COMMON.addRefinement('Color', 'BLUE');
 
  r3();
  
</script>

JSON

Copy 
<!-- Place code inside the <body> element as close to the top as possible -->
<script charset="utf-8" type="text/javascript">
  var R3_COMMON = new r3_common();
  R3_COMMON.setApiKey('abcd5432e1');
  R3_COMMON.setBaseUrl(window.location.protocol+'//integration.richrelevance.com/rrserver/');
  R3_COMMON.setClickthruServer(window.location.protocol+"//"+window.location.host);
  R3_COMMON.setSessionId('6B4D397B');
  R3_COMMON.setUserId('10987');  // if exists, set it; if not, set it as session ID
  
  // here's an example requesting recommendations for 1 page area
  R3_COMMON.addPlacementType('home_page.rr1');
  var R3_HOME = new r3_home();
  //Show only blue products.
  R3_COMMON.addRefinement('Color', 'BLUE');
  rr_flush_onload();
  
  r3();
</script>

APIs

Refinements are used to assure recommended products have a specific attribute value or values. An individual refinement is specified as a colon separated name/value pair.

Example: rfm=name:value

To specify a refinement as the existence of the attribute, you can simply omit the value.

Example: rfm=name

To specify multiple refinements, specify them as a delimited list using the pipe character ('|') as the delimiter.

Example: rfm=attributeName|attributeName1:value1|attributeName2:value2.

For more information about using the rfm parameter to add refinements in recsForPlacements API, see recsForPlacements.

Over-filtering Behavior

As noted above applying refinements or multiple refinements can lead to over-filtering of recommendations, where the returnable recommendations are not sufficient to fill the min recommendation count on a placement. The default way to address this is to remove refinements as a fallback. To disable this "fallback" simply add R3_COMMON.setRefinementFallback(false); after your R3_COMMON.addRefinement statements. Note that all refinements will be removed for all placements in the request if fallback is triggered.