Skip to main content
RichRelevance

Integration: JSON Integration Overview

Overview

This document defines the JavaScript instrumentation of the merchant’s product catalog feed required by Algonomy's recommendation engine.

Audience

This guide assumes that its readers:

  • Are experienced web or application developers
  • Are familiar with JavaScript
  • Have a background in the e-commerce/retail industry
  • Understand how to populate functions with dynamic page-specific values

Benefits

By managing data from a product catalog feed with a light JavaScript integration on a website. Algonomy actively suggests items in real-time that reflect individual consumers interests and behaviors through 40+ distinct recommendation types. This technology, called “Ensemble Learning”, is wholly unique to Algonomy in its ability to continuously evaluate its own performance, testing different approaches and constantly refining increased sales on each page.

Prerequisites

This set of documents is only a guide to help you complete the instrumentation.  The code snippets provided are samples to help showcase the proper syntax and parameters.  

How It Works

At a high level, the JavaScript "stub", which lives in the HTML of a retailer’s website, populates a number of product- and customer-related fields in a JavaScript object, transmits the fields to the Algonomy server using HTTP or HTTPS, and receives a dynamically-generated JavaScript file that modifies the eCommerce site to display relevant product recommendations.

JavaScript Integration

Algonomy provides a JavaScript library to assist with client-side integration. The library is named p13n.js (short for personalization). The current version is 2.0, and is available at https://media.richrelevance.com/rrserver/js/2.0/p13n.js The human-readable uncompressed version is available at https://media.richrelevance.com/rrserver/js/2.0/p13n_unoptimized.js. The current version is http://media.richrelevance.com/rrserver/js/1.2/p13n.js.

JavaScript in listen-only Mode & Google Analytics Dependency

Algonomy provides a feature that allows you to utilize JavaScript in a 'listen-only' mode. This implies that p13n.JS will collect user behavior data from your website without displaying any recommendations. To access these recommendations, you must make separate API calls from your server to the Personalization Cloud. You can then present these recommendations in as you prefer. Please contact your Algonomy consultant to activate this feature.

This approach offers several benefits:

1. It gives you complete control over the presentation of product recommendations or content on your website, ensuring no interference with Google Analytics.

2. The accuracy of the recommendations provided by Personalization Cloud relies solely on the quality of user behavior data gathered from your website. The listen-only mode of P13N.JS guarantees the data's integrity in an easy-to-implement manner.

Versions

All versions before Version 1.2 are deprecated.

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 the 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 before 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.
  • This is the first step in moving toward JavaScript libraries.
Size in KB 0.4 1.0 1.1 1.2 2.0
Uncompressed 33.7 51 49.3 26.7 27.6
Compressed 8.1 14.5 13.8 6.73 7.1

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.

<script src="//media.richrelevance.com/rrserver/js/2.0/p13n.js"></script>

New Native First-Party JS V2.0 Method for Tracking Shopper Behavior

As part of the platform’s initiative to move towards a privacy-first solution, a new version (version 2.0 of p13n.js) of the JavaScript library has been released and is now the master version. This version of the JavaScript library eliminates the use of third-party cookies to capture the shopper’s behavior data and uses a native first-party method to capture the relevant information to power the personalization.

https://media.richrelevance.com/rrserver/js/2.0/p13n.js

https://media.richrelevance.com/rrserver/js/2.0/p13n_unoptimized.js

Note: To get more information on how first-party Personalization client-side experience has been enhanced using API Gateway as a Reverse Proxy, refer to RR Domain Reverse Proxy.

The following table explains how the new p13n.js version 2.0 differs from the existing default version 1.2:

Sl. No.

Description

Existing Version 1.2

New Version 2.0

1

Load p13n_generated.js dynamic script on https://recs.richrelevance.com

/rrserver/p13n_generated.js

Loaded through <script> tag

Loaded through fetch call

2

Request method

GET

POST with content-type of "application/x-www-form-urlencoded;charset=UTF-8"

3

Request parameters

All the parameters (including 'rcs') are sent in the URL as query strings

For POST: The 'rcs' will be send in the request body and the rest of the parameters are sent in the URL as query strings.

4

Request cookies

All third-party cookies will be sent

No third-party cookies will be sent

5

Response for p13n_generated.js

Response body contains "rr_remote_data" (alias for "rcs") along with other scriptlets.

Response body contains "rr_remote_data" (alias for "rcs") along with other scriptlets.

6

Response cookies

All the third-party cookies, with domains "recs.richrelevance.com" or "richrelevance.com"

No third-party cookies will be received

7

rcs/rr_rcs

The "rcs" itself is created as first-party cookie and localStorage (with a default expiry duration of 364 days) is named "rr_rcs". It has only "uc" and "mvtid" third-party cookies in it.

js_01.png

The "rcs" itself is created as first-party cookie and localStorage (with a default expiry duration of 364 days) is named "rr_rcs". It has all the third-party cookies in it. Hence, the RCS value will be lengthier than the existing one and will vary for different clients, pages, calls etc.

8

Option to enable the third-party cookies

By default, the third-party cookies are enabled and there is no way to disable them.

js_02.png

By default, the third-party cookies are disabled. Can be enabled back by:

<instance of r3_common>.setNoThirdPartyCookies(false)

9

Release

At present the p13n.js is loaded from:

https://media.richrelevance.com/rrserver/js/1.2/p13n.js

The p13n.js will be released with a newer version:

https://media.richrelevance.com/rrserver/js/2.0/p13n.js

Note: The clients need to make changes to their website to load the p13n.js from the above-mentioned location.

10

p13n.js loaded from the client's own CDN

Loaded from:

https://cdn.customer.com/rrserver/js/p13n.js

The latest content of p13n.js v2.0 should be copied to the existing location:

https://cdn.customer.com/rrserver/js/p13n.js

Notes:

  • 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.
  • The default version of the JavaScript library will still be version 1.2.
  • Algonomy recommends that customers transition to the new version of JavaScript. To successfully implement this upgrade, customers will have to adjust their instrumentation as needed.
  • If you are using the common code block, as part of your piloting, change the JS version to 2.0.
<script type="text/javascript" src="//media.richrelevance.com/rrserver/js/2.0/p13n.js"></script>       
<script type="text/javascript">

When you load the Algonomy library, you need to load the new version of the library specifically as following:

<script src="http://media.richrelevance.com/rrserver/js/2.0/p13n.js"/>

JavaScript Calls

The basic order of calls is as follows: 

  1. Load the Algonomy library right after the <body> tag: 
     <script src="http://media.richrelevance.com/rrserver/js/2.0/p13n.js"/> 

Note: media.richrelevance.com is hosted on our Content Delivery Network (CDN) partner, Akamai 

  1. Populate a few variables:
    1. Your API key 
    2.  What type of page this is (home, category, search, product, cart)
    3. Page-specific variables (product info on product pages, category info on category pages, search terms on search pages)
    4. Customer-specific variables (session id, user id if available) 
  2. Call "r3()" after the variables are defined. This function lives inside "p13n.js". It packages the variables' values and sends them to Algonomy servers while the rest of your page is still loading. This minimizes the impact on page load time by making it page-load-friendly. The results are returned in a file called "p13n_generated.js". The file contains the JavaScript objects used to display recommendations

Instrumenting Pages

Page Types

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. 

Once you know what page type you’re working with, follow the example JavaScript integration code and modify it so that the correct values must are passed, sending the context details to the Relevance Cloud. The Page types currently available are: 

The COMMON Code Block 

It is highly recommended that the following JavaScript be added to every page within the merchant’s website – including the pages that do not display product recommendations.  This allows Algonomy to observe the complete click stream of the customer and deliver more personalized recommendations. 
 
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:  

<!-- NOTE: leave out http: and https: and the browser will use the current page's protocol by default -->     
<script type="text/javascript" src="//media.richrelevance.com/rrserver/js/1.2/p13n.js"></script>       
<script type="text/javascript">
         var R3_COMMON = new r3_common();
         R3_COMMON.setApiKey('[api_key]');
         R3_COMMON.setBaseUrl('http://[integration] or [recs].richrelevance.com/rrserver/');
          R3_COMMON.setSessionId('[user_session_id]');
          R3_COMMON.setUserId('[user_id]'); // if exists, set it; if not, omit tag
          r3();
  </script>      

Notes:

  • 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 

Algonomy servers have two distinct modes of operation: listen mode, and display mode. While in listen mode the instrumented javascript silently feeds the Algonomy server user behavior data. A site must be instrumented in listen mode for a period of time before relevant recommendations can be displayed to users.  
 
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:  http://yourstore.com/category?id=123...ceDisplay=true 
 
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:  http://yourstore.com/category?id=123...DummyData=true