Integration: Refinements
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
Use the rfm
parameter to add refinements when you call 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.