Testing and Debugging
This document identifies some useful ways of debugging and user acceptance testing Recommend on your site.
Audience
The debugging section of this guide assumes that its readers:
- Are experienced web or application developers
- Are familiar with FireBug or comparable web development tools
- Are familiar with XML and JavaScript and debugging
The user acceptance testing section of this guide assumes that its readers:
- Are familiar with the merchant’s product catalog and high-level merchandising guidelines
- Have a background in the retail industry
Introduction
How Recommendations Work
The enRICH Personalization Engine uses Ensemble Learning to facilitate competition among many independent algorithms (recommendation types), wherein each makes use of different kinds of user behavior and product catalog data. The enRICH Engine then decides, in real time, which algorithm is best matched to a particular shopper’s needs at a specific place and time.
Which Pages to Test?
Your site may have any mix of the page types or products below. Your Algonomy Client Solutions Engineer or Relationship Manager can provide you with a matrix of pages to test.
Page types:
- Home
- Search
- Category
- Item
- Error
- Cart
- Add To Cart
- Checkout Complete
How to View Recommendations
To view recommendations prior to Listen Mode—before the JavaScript instrumentation code has been deployed to production and before recommendation models have been built—append r3_useDummyData=true” to the browser’s URL. Example:
http://yoursite.com/category?id=123&r3_useDummyData=true
The “dummy data” model simply returns random products from your catalog so that you can verify placement locations on the page are set correctly.
To view recommendations in while in Listen Mode, append “r3_forceDisplay=true” to the browser’s URL. Example:
http://yoursite.com/category?id=123&r3_forceDisplay=true
Keep in mind that recommendation models may not yet be mature as Recommend uses Listen mode to collect the behavioral data that drives relevance.
Debugging
Using Firebug to Review Page Types
What is Firebug?
Firebug is a tool used by developers to edit, debug and test HTML, CSS and JavaScript live on any webpage. Firebug is a Firefox browser add-on. First you have to download the Firefox browser (firefox.com).
How to View Parameters
After you have firebug/net tab enabled, you are ready to begin reviewing the parameters passed to {rr}:
- Load an instrumented page.
- Click “JS” on the tool bar to filter out everything except JavaScript.
- Look for a file named “p13n_generated.js” in the list.
- Press the “+” symbol next to “GET p13n_generated.js?…”
- Press the “Params” tab and review the parameters being passed to {rr}.
If you don’t see p13n_generated.js in the list, the page is not instrumented or isn’t functioning properly.
Begin the Review
Each page type has a different set of variables required to make the page function properly, some variables are optional. You may see additional parameters being passed depending on your site’s requirements. Optional values will be marked with a gray background.
Notes:
- “pt” is not always present, but if recs are being requested it is required
- “u” is not required, but strongly recommended on every page
- Session Id should stay consistent through the entire shopping experience
- User Id should stay consistent from visit to visit
- All category ids, item ids, brands, and refinements passed to {rr} must match exactly what is provided in the feed, be sure to check for case sensitivity, and trailing spaces.
Page Types
Home Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |home_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| pte | T | Signifies that no recs were requested, will not be present on pages where recs are displaying, may exist on every page |
| s | Session | |
| u | User id | |
| ssl | T | SSL encrypted, may exist on any page |
| pref | Referring page’s URL, may exist on every page | |
| ctp | | | String to be added to URL of product clicked from recommendations, may exist on every page |
| cts | Domain name to use when product is clicked from recommendations, may exist on every page | |
| ts | 1235465879413 | Timestamp |
Category Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |category_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| pte | T | Signifies that no recs were requested, will not be present on pages where recs are displaying. |
| s | Session | |
| u | User id | |
| c | Id of category currently being viewed | |
| cn | Name of category currently being viewed, ready to display to user | |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
Item Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |item_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| pte | T | Signifies that no recs were requested, will not be present on pages where recs are displaying. |
| s | Session | |
| u | User id | |
| p | Id of product currently being viewed | |
| re | True/False – sets the current product as recommendable or not | |
| cs | Category Id & Name the user navigated to this product from.
Example: 10178:Shoes |
|
| fpb | Brand of product shown on current page, may also be used on category page | |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
Search Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |search_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| s | Session | |
| u | User id | |
| st | | | Phrase user searched for |
| p | || | Up to 15 product ids returned by search, separated by pipe |
| rfm | |: | One or more refinements user has added to page in name:value pairs separated by pipe
Example: |color:blue|metal:gold |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
Add To Cart Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |add_to_cart_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| s | Session | |
| u | User id | |
| atcid | || | Product Ids being added to cart, separated by pipe |
| rfm | |: | One or more refinements user has added to page in name:value pairs separated by pipe
Example: |color:blue|metal:gold |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
Cart Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |cart_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| s | Session | |
| u | User id | |
| p | || | Product Ids currently in cart, separated by pipe |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
Purchase Complete Page
| Parameter | Value | Definition |
|---|---|---|
| a | API Key | |
| l | 1 | Present every successful request |
| pt | |purchase_complete_page | Page Type & placement requests.
Value may appear as: |page_type.placement1|page_type.placement2|page_type.placement3 |
| s | Session | |
| u | User id | |
| o | Order id | |
| p | || | Product Ids purchased, separated by pipe |
| pp | || | Unit price of products purchased, separated by pipe |
| q | || | Quantity of each product purchased, separated by pipe |
| pref | Referring page’s URL | |
| ts | 1235465879413 | Timestamp |
JavaScript Integration Validation
Are There JavaScript Errors on the Page?
Oftentimes, several pieces of JavaScript code are instrumented in the same <script> block. Code prior to the Algonomy code may cause an error, which stops the rest of that <script>’s contents from running.
If you don’t see recommendations on the page, first check if there are JavaScript errors on the page. Check the line number of the error. Does the JavaScript error involve content in p13n.js (the Algonomy library) or p13n_generated.js (the Algonomy response containing recommendations data), or is the error from another source?
If the error is within Algonomy code, please escalate to your Client Solutions Engineer or Relationship Manager. Provide details on how to reproduce the error including the browser you are using, the url you are viewing, and the error text and line number.
Otherwise, if the error is occurring before the r3() function in a <script> tag is called (that’s the main Algonomy function that compiles and sends a request to the Algonomy servers and listens for the response), then the source of the problem is likely outside of the integration of recommendations code, and the issue should be escalated to the party responsible for that code.
Is the p13n.js Library Called Before the R3_COMMON Section?
The p13n.js library file will usually be called right after the opening <body> tag, or sometimes in the <head> tag or before the closing <body> tag. This library must be called before the integration code, as the variables in the integration code depend on functions in the p13n.js library to be set.
If p13n.js exists, make sure that the path is correct by copying the full path to p13n.js and pasting it into a new browser window.
Is the r3() Function Called on the Page?
The r3() function should be called after the variables are defined on the page, such as the R3_COMMON, R3_ITEM, R3_HOME, etc. It will generally look something like this:
<script> var R3_COMMON = new r3_common(); R3_COMMON.setApiKey(‘YOURAPIKEY’); R3_COMMON.setBaseUrl(‘http://recs.RichRelevance.com/rrserver’); R3_COMMON.setUserId(‘A_USER_ID’); R3_COMMON.setSessionId(‘A_SESSION_ID’); R3_COMMON.addPlacementType(‘home_page.content’); r3(); </script>
Is the p13n_generated.js File Larger than 300 Bytes?
If p13n_generated.js is not larger than 300 bytes, it means that there were no recommendations returned.
Check the following:
- In Firefox using Firebug, check Net -> JS to make sure that p13n_generated is returned
- Do the page_area names in set in R3_COMMON.addPlacementType() and then called in r3_placement() match? Are there any typos?
- Are recommendations returned on other pages of the same page type (i.e. on other item pages, is p13n_generated.js returning larger than 300 bytes)?
It could be that there are no products to recommend on this page because the page information is new (a category we don’t know about yet), or a merchandising rule has been set to suppress recommendations (check with your account manager), or there’s a misconfiguration between page area names in the dashboard (check with your Client Solutions Engineer).
Is the rr_flush_onload(); called after the last r3_placement()?
The rr_flush_onload() function tells the browser that recs are ready for display without waiting for the document.ready function hook to be fired off. It should always be included after the last r3_placement() call so that recommendations are loaded as soon as they are available, rather than waiting for the DOM to load.
Not Seeing Recommendations on HTTPS Pages?
Check to make sure that the links to the p13n.js file and any other supporting files are requested on HTTPS pages with the correct HTTPS protocol, or the files won’t be loaded and no recs will be allowed to return. Good rule of thumb is to check for protocol of the page in JavaScript:
if(location.protocol == “https:”){
rrLink = ‘https://’
}else{
rrLink = ‘http://’
}
var R3_COMMON = new r3_common();
R3_COMMON.setApiKey(‘YOUR_API_KEY’);
R3_COMMON.setBaseUrl(rrLink + ‘recs.RichRelevance.com/rrserver/’);
Do You use a Technology that Rewrites the Onload Event?
Certain technologies that piggyback on the onload event can also modify it in an unfriendly way. For example, SLI redefines the onload function to trigger its search code rather than append a function to the onload event, which results in anything depending on onload firing not getting called.
To make sure recommendations are always loaded, the rr_flush_onload() event should always be included after the last r3_placement() call.
Look and Feel
Are Recommendations Displaying Correctly?
Did your site’s CSS files change recently? If you’re seeing unexpected layouts in recommendations, it’s may be due to changes in your CSS or HTML where elements with classes applied are not inheriting the styles appropriately.
Use firebug to inspect the elements of the recommendation and verify that the appropriate CSS is being applied to the elements in question.
Do the Paths to the CSS Files Exist in the HTML Source?
If you’re applying styles that should exist on the page, make sure the CSS files are included correctly and are in the right order (especially if inheritance/overrides are used from page type to page type).
To verify that the paths resolve correctly, copy the path of the CSS file(s) in question and open them in a new browser window. We’ve seen several cases where a CSS file change was available in the dev/test environment but didn’t get checked in and therefore didn’t make it out to production.
Are the CSS Classes Applied to Recommendations in the CSS Files?
Use firebug to inspect the elements of the recommendation; in the right column you’ll see the inheritance of CSS established in the accompanying site CSS files.
Testing for Illegal XML in the Feed
When an XML element is parsed, all of the text within the XML tag is also parsed. This is done because it is possible, and highly likely, that the text will contain other XML elements. Because of this, there are certain characters that are deemed illegal since they will be misinterpreted by the XML parser. To avoid causing the XML parser to break, there are two preferred methods:
Entity Reference
Replace the characters with their corresponding entity reference:
| Illegal Character | Entity Reference | Description |
| < | < | Less Than |
| > | > | Greater Than |
| & | & | Ampersand |
| ‘ | ' | Apostrophe |
| “ | " | Quotation Mark |
CDATA Section
Enclose the tag value within a CDATA section. A CDATA section begins with “<![CDATA[” and ends with “]]>”:
| Condition | Example |
| Without CDATA | <example>this is the value</example> |
| With CDATA | <example><![CDATA[this is the value]]></example> |
Testing XML Feeds as you Build Them
To ensure that your XML feed will parse correctly by our platform, we suggest that you test for XML errors before sending it. There are a variety of libraries and online tools you can use such as:
User Acceptance Testing
Below are steps to take to make to verify that recommendations are contextually relevant and production-ready.
Do Recommendations Contain Content Relevant to the Current Page?
Is your site using “genres?” These are top-level categories that align with what merchants refer to as “departments” or “verticals.” If so, look for any products that live outside of the current genre; you should never see “Automotive Department” products in a “Baby Department” recommendation set (e.g., “People who viewed this item also viewed”), unless it’s a user-specific strategy like “Recently Viewed Items.”
Do Recommendation Strategies Make Sense in Context?
Your Relationship Manager will enable a best-practice set of recommendation strategies for each page type. The recommendation engine will test these strategies among a subset of traffic and display the top performers more prominently.
Step through the enabled strategies to ensure that they make sense in a given situation. While on a page, refresh it several times and look for any outliers with the selected recommendations strategies—things that just don’t seem to fit in context. For example, is a site-wide top sellers strategy displaying on a Category page? Is a “People who viewed this also viewed” strategy displaying on the Add to Cart or Cart pages? This may sometimes mean stepping into the merchant role and thinking critically about different ways that your customers shop.
Verify that the Number of Placements is Correct
In the design phase, the number of recommendation placements per page will be established. If you are not seeing the expected placements on a particular page (e.g., an Item page), check other Item pages. It may be the case that this particular product may not yet have enough browse traffic to generate one or more sets of robust recommendations. This placement suppression is not an error; the recommendation engine is performing as expected.
However, there should never be empty carousels or containers displaying where a set of recommendations is supposed to appear. Contact your Relationship Manager if you see this occurring.
Important note: if the recommendation engine is not able to identify a qualifying set of recommendations for a particular page, recommendations will not be shown.
Are There Any Incorrectly Displaying Characters?
Identify products with registration, trademark, foreign language, etc., in the product titles and make sure that those characters are displaying correctly.
Is the Strategy Message Wrapping Too Many Lines?
Does the strategy message make sense and engage the customer?
On some pages (e.g., Item), strategy messages may make use of the current product name in the context. If the product name is too long, it can cause the strategy message to wrap too many lines. Depending on the design of the site, two lines are generally appropriate, but you should avoid three.
If the placement has a vertical orientation, it usually makes sense not to reference the product name to avoid excessive wrapping. Your Relationship Manager can configure this for you.
Are the Recommendations Attractive and Engaging?
Think best practices. Do your customers understand what the call to action is when looking at the recommendations? Are the buttons and links well formed? Do they match the style guide of the site? Are the strategy messages compelling and consistent with how you would address your customers?
Select Several Recommended Products and Verify Data Displayed is Correct
Verify that the click-through links are functioning properly and that the displayed product attributes—price, description, pictures, etc.—meet expectation.