This guide assumes that its readers:
- Are experienced web or application developers
- Have a background in the e-commerce/retail industry
- Understand how to populate functions with dynamic page-specific values
This set of documents are only guides to help you complete the instrumentation. The code provided are samples to help showcase the proper syntax and parameters.
How It Works
Version 0.4 is deprecated. Please contact your Algonomy Account Manager for upgrade.
Version 1.0 is deprecated. Please contact your Algonomy Account Manager for upgrade.
Version 1.1 is deprecated. Please contact your Algonomy Account Manager for upgrade.
Version 1.2 is no longer the preferred version. This version removes Flash support and other unused code resulting in a 50% reduction in file size. Please contact your Algonomy Account Manager for upgrade.
Version 2.0 is the current version. This version removes the use of third party cookies and makes use of First party information to track shopper's behavior.
Updating Your Version
All existing integrations will not be forced to update the version to 2.0. Customers are encouraged to migrate to the new version before June 2024 when Google removes the support of third party cookies.
- Migrating prior to the hard-cut off date provides you an opportunity for instrumentation review to ensure that all calls are going to the correct version.
- Version 2.0 uses the POST method to capture and transmit data from your run time to the personalization cloud.
- Version 2.0 concatenates all the required information against "rr_rcs "which itself is a first party cookie, which is detailed in the subsequent section.
|Size in KB||0.4||1.0||1.1||1.2||2.0|
All 1.x and earlier versions adhere to the same interface and can be upgraded simply by changing the version number in the script request.
Example: The version number is bolded in the example below. Change the version number to the updated version in all integration points.
- Do not restrict the length of the rcs/rr_rcs value as the personalization cloud depends on this parameter to capture the shopper’s usage or behavioral data.
- Algonomy recommends customers to pilot the new JS version. To upgrade to the new JS version, customers would need to make the following changes to their instrumentation.
- If you are using the common code block, as part of your piloting, change the JS version to 2.0.
The basic order of calls is as follows:
- Load the Algonomy library right after the <body> tag:
Note: media.richrelevance.com is hosted on our Content Delivery Network (CDN) partner, Akamai
- Populate a few variables:
- Your API key
- What type of page this is (home, category, search, product, cart)
- Page-specific variables (product info on product pages, category info on category pages, search terms on search pages)
- Customer-specific variables (session id, user id if available)
Whether you’re using HTML or JSON responses, the first step in integrating a page on your site is deciding which page type most closely matches the page you’re working on. Different types of pages have different requirements. For example, a product detail page (PDP) needs to include information about the featured product. These details provide the context, which is essential for personalizing the shoppers’ experience.
Since each merchant may have their own naming convention for the pages within their site, Algonomy has tried to come up with an all-inclusive set of generic names that can be used to describe each page. These page types play a significant role in the recommendation process since they will influence which recommendation strategy is determined in real-time to have the highest probability of influencing the customer to make a purchase.
The COMMON Code Block
The call to the Algonomy library, packaging of data, server request and server response are designed to run in parallel with your page load, and are non-blocking. There is no need to do any work on your side to delay or time requests - and requests should not wait until after the DOM is 'ready’ before being called.
This instrumentation code should live as soon after <body> as possible:
- If a customer has not logged into the merchant’s website and been assigned a unique ID, it is not necessary to call R3_COMMON.setUserId(). Incorrect usage of this tag can cause a degradation in the quality of recommendations.
- It is necessary to call r3(); on every page that is instrumented.
- Optional: to "seed" a page with specific categories (for example on the homepage), just add them to the array below and place this code before the r3() function:
r3_categoryHintArray = ['CATID1','CATID2','CATID3']; var r3_categoryHintSeed = r3_categoryHintArray[Math.floor(Math.random()* r3_categoryHintArray .length)]; R3_COMMON.addCategoryHintId(r3_categoryHintSeed);
Viewing Recommendations Prior to Display Mode
Recommendations will only display after enough data has collected, and the client has given Algonomy approval to change to display mode.
To test instrumentation prior to listen mode our system can produce recommendations based on "dummy data”. This allows you to test look and feel to a limited extent and verify that requests are getting processed by Algonomy. Algonomy will work closely with you to insure instrumentation is correct and is collecting all data properly.
Once code is deployed to production in listening mode, you can override "listening mode" and force display of real recommendations by adding
r3_forceDisplay=true to the browser's URL:
Note: If recommendations are not displayed, possibly our system has not collected enough data to produce real recommendations.
We highly recommend deploying all of the integration code - r3_placement() calls included - to production so that you can preview recommendations display in a live environment using the "force display" method.
You can also use the dummy data model any time by adding
r3_useDummyData=true to the browser's URL: