How to Enable Experience Browser

Overview

The Experience Browser brings to retailers a new Personalization experience right on their own site. With Experience Browser you can see how your placements are performing overall and test responses for individual users. These instructions explain how to enable Experience Browser for your site.

Users tasked with setting up their site to use Experience Browser. Some experience with code and the Algonomy Omnichannel Personalization products being used on the website would be beneficial. Users should also have an Algonomy Portal account and access to the Admin functions on the Omnichannel Personalization Dashboard.

Enabling Experience Browser using CFRAD

  1. To generate a CFRAD key, on the Algonomy Omnichannel Personalization Dashboard, go to Admin >Tools.

    Graphical user interface, text, application Description automatically generated

  2. In the Tools window, go down to the Client Facing RAD secret key section.

    Once generated, the key is what will be added to the URL to launch the Experience Browser (?cfrad=<key> or &cfrad=<key>). Click the Render Experience Browser URL to have Algonomy provide you the URL+key to copy.

  3. To add an internal domain for the site by navigating to Admin > Internal Domains. The internal domain is validated as part of the login process with Experience Browser. When there are multiple websites, all managed from a single account in the dashboard, each site should have its own internal domain added.

    Graphical user interface Description automatically generated with medium confidence

  4. The list page will show any existing Internal Domains, along with a button to +Add Internal Domain button, as well as Edit and Delete buttons.

    Graphical user interface Description automatically generated with medium confidence

  5. To add a new domain, click the + Add Internal button.

  6. Enter the domain name on the pop-up window and click Save.

  7. Launch Experience Browser by using the URL with the cfrad parameter. For example: //labs.richrelevance.com?cfrad=showcaseparent_rad_key

    Note: Steps 1 through 6 only have to be performed once. After the key has been generated and the domain created, you will continue to use that same URL to access the Experience Browser on your site.

  8. Login with your Portal ID. This is the same username and password you use to login to the Algonomy Omnichannel Personalization dashboard.

Experience Browser supports federated Single Sign-on (SSO) with Algonomy Identity Service (OneLogin) which provides both authentication and authorization. When you launch the Experience Browser URL, a login window will be rendered in a separate tab on your web browser. Please note that you must allow the pop-up to enable the login process.

 

After successful log in with your Algonomy credentials or corporate credentials (in case your organization have configured Federated SSO), you will be able to log in to the Experience Browser. If you already have an active session with Algonomy Identity service, prior to accessing Experience Browser, then you will be able to access the Experience Browser (on the same browser) without having to enter the credentials. If you do not have an existing session with Algonomy Identity service, then you will be redirected to enter the credentials.

Note: Algonomy Identity service uses OneLogin Identity and Access Management service for Authentication and Authorization.

Enabling Experience Browser for Server-Side/API integrated sites

  1. To generate a CFRAD key, on the Algonomy Omnichannel Personalization Dashboard, go to Admin >Tools.

  2. In the Tools window, go down to the Client Facing RAD secret key section.

  3. The CFRAD key should be passed to recsForPlacements API as a query parameter in order to return the rr_annotations object.

  4. The rr_annotations object should be attached to global browser window object like this: window.rr_annotations or window.rr_annotations_array (array of rr_annotations objects).

  5. The Experience Browser JavaScript file should be loaded on the web page.

  6. Once those steps are complete, the Experience Browser will start, parse rr_annotations or rr_annotations_array and display analytics data in the user interface.

  7. After the API call, the cfrad cookie will be set in the browser allowing website navigation with Experience Browser displayed on every page.

Note: To see some Experience Browser reports user will need to have site access.

Developer Instructions

For starting Experience Browser after recsForPlacements API call from the browser:

  1. Define the recsForPlacementsCallback function provided below in the global scope. This function will start Experience Browser on the page.

  2. Check if the cfrad parameter is present in the current URL.

  3. Make a valid API call with the cfrad parameter, using the recsForPlacementsCallback as a callback function.

See an example implementation of this logic below:

Example of API call from the browser
Copy 

// Use IIFE for creating local scope (optional)
(function() {
  // Get cfrad parameter from current URL:
  var cfrad = new URLSearchParams(window.location.search).get("cfrad");
  // Define endpoint URL (jsonp should be set to true)
  var apiUrl = "https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements?jsonp=true&";
  // Append cfrad parameter to apiUrl:
  if (cfrad) apiUrl += "cfrad=" + cfrad + "&";
  // Append other required query parameters such as placements, apiKey, apiClientKey, etc. to make valid API call.
  // See more details about recsForPlacements API: https://help.richrelevance.com/3_Recommend/Recommend:_APIs/recsForPlacements
  // Make recsForPlacements API call with cfrad query parameter, use recsForPlacementsCallback as a callback function
  // jQuery example:
  $.ajax({
    url: apiUrl,
    dataType: "jsonp",
    jsonp: "jcb"
  }).done(function(response) {
    recsForPlacementsCallback(response);
    // Do something else with the response here.
  });
  // Vanilla JS example without jQuery:
  var script = document.createElement("script");
  script.src = apiUrl + "&jcb=recsForPlacementsCallback";
  document.getElementsByTagName("head")[0].appendChild(script);
})();

  1. After making the recsForPlacements call, the cfrad cookie will be set automatically, the rr_annotations object will be returned in the response and passed to the recsForPlacementsCallback function which will load and start Experience Browser.

Copy 
function recsForPlacementsCallback(response) {
  var app, script;
  // Check if rr_annotations object was returned in the response
  if (response && response.rr_annotations) {
    // If we have rr_annotations_array push rr_annotations object there, otherwise create it with rr_annotations inside
    if (window.rr_annotations_array) {
      window.rr_annotations_array.push(response.rr_annotations);
    } else {
      window.rr_annotations_array = [response.rr_annotations];
    }
    // Check if Experience Browser was already loaded on the page (it creates rr_experience_browser global variable)
    if (window.rr_experience_browser) {
      rr_experience_browser.start();
    } else {
      // If Experience Browser is missing, load it from Algonomy Omnichannel Personalization cdn, it will start automatically and parse rr_annotations
      script = document.createElement("script");
      script.src = "//cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js";
      script.async = true;
      document.getElementsByTagName("head")[0].appendChild(script);
    }
  } else {
    console.log("recsForPlacementsCallback: rr_annotations is missing");
  }
}

Note: Some websites have client-side integration (p13n.js) and call recsForPlacements API at the same time. In this case, Experience Browser will be loaded automatically after the first request is returned (either p13n.js or recsForPlacements), then only start method of Experience Browser will be called. After every call to recsForPlacements API, the rr_annotations objects will be pushed into rr_annotations_array by a callback function for avoiding overwriting annotations data after every request. Client-side integration does not push rr_annotations into this array yet, so it is safer to make only one p13n.js call per page.

For starting Experience Browser after personalize API call from the server:

  1. Check if cfrad parameter is passed as a query parameter.

  2. Make a valid API call to personalize API with cfrad parameter.

  3. Attach rr_annotations returned by API to global window object in the browser.

  4. Load Experience Browser JS file: //cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js

  5. Experience Browser will start and parse rr_annotations object or rr_annotations_array (array of rr_annotations objects).

See an example implementation of this logic below:

Copy 
// Use IIFE for creating local scope (optional)
(function() {
  // Get cfrad parameter from current URL:
  var cfrad = new URLSearchParams(window.location.search).get("cfrad");
  // Define endpoint URL
  var apiUrl = "https://recs.richrelevance.com/rrserver/api/personalize?";
  // Append cfrad parameter to apiUrl:
  if (cfrad) apiUrl += "cfrad=" + cfrad + "&";
  // Append other required query parameters such as placements, apiKey, apiClientKey, etc. to make valid API call.
  // See more details about personalize API: https://help.richrelevance.com/Relevance_Cloud/Relevance_Cloud%3A_Core_APIs/Personalize_API
  // Make personalize API call with cfrad query parameter, use personalizeCallback as a callback function
  // jQuery example:
  $.ajax({
    url: apiUrl,
    dataType: "jsonp",
    jsonp: "callback"
  }).done(function(response) {
    personalizeCallback(response);
    // Do something else with the response here.
  });
  // Vanilla JS example without jQuery:
  var script = document.createElement("script");
  script.src = apiUrl + "&callback=personalizeCallback";
  document.getElementsByTagName("head")[0].appendChild(script);
})();

  1. After making personalize call cfrad cookie will be set automatically, rr_annotations object will be returned in the response and passed to personalizeCallback function which will load and start Experience Browser.

Copy 
function personalizeCallback(response) {
  var app, script;
  // Check if rr_annotations object was returned in the response
  if (response && response.rr_annotations) {
    // If we have rr_annotations_array push rr_annotations object there, otherwise create it with rr_annotations inside
    if (window.rr_annotations_array) {
      window.rr_annotations_array.push(response.rr_annotations);
    } else {
      window.rr_annotations_array = [response.rr_annotations];
    }
    // Check if Experience Browser was already loaded on the page (it creates rr_experience_browser global variable)
    if (window.rr_experience_browser) {
      rr_experience_browser.start();
    } else {
      // If Experience Browser is missing, load it from Algonomy Omnichannel Personalization cdn, it will start automatically and parse rr_annotations
      script = document.createElement("script");
      script.src = "//cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js";
      script.async = true;
      document.getElementsByTagName("head")[0].appendChild(script);
    }
  } else {
    console.log("personalizeCallback: rr_annotations is missing");
  }
}

Note: Some websites have client-side integration (p13n.js) and call personalize API at the same time. In this case Experience Browser will be loaded automatically after first request comes back (either p13n.js or personalize), then only initialize method of Experience Browser will be called. After every call to personalize API  rr_annotations objects will be pushed into rr_annotations_array by a callback function for avoiding overwriting annotations data after every request. Client-side integration does not push rr_annotations into this array yet, so it is safer to make only one p13n.js call per page.

For starting Experience Browser after recsForPlacements API call from the server:

  1. Check if the cfrad parameter is passed as a query parameter.

  2. Make a valid API call to the recsForPlacements API with the cfrad parameter.

  3. Attach the rr_annotations returned by API to the global window object in the browser.

  4. Load the Experience Browser JS file: //cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js

  5. Experience Browser will start and parse rr_annotations object or rr_annotations_array (array of rr_annotations objects).

See an example implementation of this logic below:

Example of API call from the server (Node.js + Express + ejs as a template engine)
Copy 
 var express = require("express"),
  app = express(),
  bodyParser = require("body-parser"),
  request = require("request");
app.use(bodyParser.urlencoded({ extended: true }));
app.set("view engine", "ejs");
// This middleware will check if cfrad key is present, make recsForPlacements API call and allow using rr_annotations in the ejs template
app.use(function(req, res, next) {
  // Get cfrad key from request query parameters
  var cfrad = req.query.cfrad;
  // Define endpoint URL
  var apiUrl = "https://recs.richrelevance.com/rrserver/api/rrPlatform/recsForPlacements?";
  // Append cfrad parameter to apiUrl:
  if (cfrad) apiUrl += "cfrad=" + cfrad + "&";
  // Append other required query parameters such as placements, apiKey, apiClientKey, etc. to make valid API call.
  // See more details about recsForPlacements API: https://help.richrelevance.com/3_Recommend/Recommend:_APIs/recsForPlacements
  // Use request library with jar set to true, this will allow user to omit cfard parameter in URL while cfrad cookie is valid
  request({ uri: apiUrl, jar: true }, function(error, response, body) {
    if (!error && response.statusCode === 200) {
      var data = JSON.parse(body);
      var rr_annotations = data.rr_annotations;
      // Make rr_annotations_array property available in every ejs template
      res.locals.rr_annotations_array = [];
      res.locals.startExperienceBrowser = false;
      if (rr_annotations) {
        // If you need to make multiple API calls push every rr_annotations object into this array after every call
        res.locals.rr_annotations_array.push(rr_annotations);
        res.locals.startExperienceBrowser = true;
      }
      // We need a String value in the template
      res.locals.rr_annotations_array = JSON.stringify(res.locals.rr_annotations_array);
      // Call next to let the application continue execution
      next();
    }
  });
});

If the cfrad key is present and the rr_annotations are returned, the generated web page will be sent back to the user with two scripts.

Inside ejs template:

Copy 
<% if (startExperienceBrowser) { %>
  <script>
    // Make rr_annotations_array available for Experience Browser, it will parse it or rr_annotations object found in global scope.
    window.rr_annotations_array = <%- rr_annotations_array %>;
  </script>
  <!-- Load Experience Browser -->
  <script src="//cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js"></script>
<% } %>

Note: The Experience Browser relies on rrserver links when highlighting placements, so please make sure they are rendered on the page.

Copy 
<a href="//recs.richrelevance.com/rrserver/click?pa=placement_name">
  **Placement html**
</a>

Alternatively you can use the data-placement-type attribute in your html:

Copy 
<div data-placement-type="placement_name">
  **Placement html**
</div>

If both the rrserver links and the data-placement-type attribute are missing on the page, Experience Browser will start in Undocked Mode, which does not highlight the placements, but allows the user to select the placement from a drop-down menu.

Graphical user interface, application, Teams Description automatically generated

For starting Experience Browser after personalize API call from the server:

  1. Check if cfrad parameter is passed as a query parameter.

  2. Make a valid API call to personalize API with cfrad parameter.

  3. Attach rr_annotations returned by API to global window object in the browser.

  4. Load Experience Browser JS file: //cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js

  5. Experience Browser will start and parse rr_annotations object or rr_annotations_array (array of rr_annotations objects).

See an example implementation of this logic below:

Example of API call from the server (Node.js + Express + ejs as a template engine)
Copy 
var express = require("express"),
  app = express(),
  bodyParser = require("body-parser"),
  request = require("request");
app.use(bodyParser.urlencoded({ extended: true }));
app.set("view engine", "ejs");
// This middleware will check if cfrad key is present, make personalize API call and allow using rr_annotations in the ejs template
app.use(function(req, res, next) {
  // Get cfrad key from request query parameters
  var cfrad = req.query.cfrad;
  // Define endpoint URL
  var apiUrl = "https://recs.richrelevance.com/rrserver/api/personalize?";
  // User-Agent header is required
  var headers = {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/57.0.2987.133 Safari/537.36'};
  // Append cfrad parameter to apiUrl:
  if (cfrad) apiUrl += "cfrad=" + cfrad + "&";
  // Append other required query parameters such as placements, apiKey, apiClientKey, etc. to make valid API call.
  // See more details about personalize API: https://help.richrelevance.com/Relevance_Cloud/Relevance_Cloud%3A_Core_APIs/Personalize_API
  // Use request library with jar set to true, this will allow user to omit cfard parameter in URL while cfrad cookie is valid
  request({ uri: apiUrl, jar: true, headers: headers }, function(error, response, body) {
    if (!error && response.statusCode === 200) {
      var data = JSON.parse(body);
      var rr_annotations = data.rr_annotations;
      // Make rr_annotations_array property available in every ejs template
      res.locals.rr_annotations_array = [];
      res.locals.startExperienceBrowser = false;
      if (rr_annotations) {
        // If you need to make multiple API calls push every rr_annotations object into this array after every call
        res.locals.rr_annotations_array.push(rr_annotations);
        res.locals.startExperienceBrowser = true;
      }
      // We need a String value in the template
      res.locals.rr_annotations_array = JSON.stringify(res.locals.rr_annotations_array);
      // Call next to let the application continue execution
      next();
    }
  });
});

If cfrad key is present and we got rr_annotations back - generate web page which will be sent back to the user with 2 scripts.

Inside ejs template:

Copy 
<% if (startExperienceBrowser) { %>
  <script>
    // Make rr_annotations_array available for Experience Browser, it will parse it or rr_annotations object found in global scope.
    window.rr_annotations_array = <%- rr_annotations_array %>;
  </script>
  <!-- Load Experience Browser -->
  <script src="//cdn.richrelevance.com/dashboard/applications/cfrad/dist/index.min.js"></script>
<% } %>

Note: Experience Browser relies on rrserver links when highlighting placements, so please make sure they are rendered on the page.

Copy 
<a href="//recs.richrelevance.com/rrserver/click?pa=placement_name">
  **Placement html**
</a>

Alternatively you can use data-placement-type attribute in your html:

Copy 
<div data-placement-type="placement_name">
  **Placement html**
</div>

If both rrserver links and data-placement-type attribute are missing on the page Experience Browser will start in Undocked Mode - without highlighting but with  placement drop down selector.