Integration: Refinements

Last updated
Save as PDF

Refinements can be added to apply filters to the recommendations that would be returned. This can be done for an 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:

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

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

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

Ask your Algonomy contact to enable Refinements for your site.
Create the integration code on each of the pages on your site, following the HTML integration and JSON integration guides.
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

<!-- 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

<!-- 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.