Testing and Debugging

Overview

This document identifies some useful ways of debugging and user acceptance testing Recommend on your site.

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 customer’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}:

1. Load an instrumented page.

2. Click “JS” on the tool bar to filter out everything except JavaScript.

3. Look for a file named “p13n_generated.js” in the list.

4. Press the “+” symbol next to “GET p13n_generated.js?”

5. Press the “Params” tab and review the parameters being passed to {rr}.

If you do not see p13n_generated.js in the list, the page is not instrumented or is not 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

Category Page

Item Page

Search Page

Add To Cart Page

Cart Page

Purchase Complete Page

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 Omnichannel Personalization 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 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:

CDATA Section

Enclose the tag value within a CDATA section. A CDATA section begins with “<![CDATA[” and ends with “]]>”:

Testing XML Feeds as you Build Them Edit section

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:

• http://w3cschools.com

• http://validator.w3.org

• http://www.validome.org

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