NAV Navbar

Introduction

/*
 * Initialize the custom recommendations client with all of the preconfigured options
 */
const recommendations = new ConstructorioSearch.Recommendations({
  clientOptions: {
    key: '<your_api_key>'
  }
});

The Constructor.io JavaScript recommendations client provides a user interface to display personalized recommendations to your customers.

The recommendations client renders specific UI components into designated elements on any page. There are also event handlers that you can hook into and respond to user actions.

Every Constructor.io customer will get their own customized version of the recommendations client with preconfigured UI options to match their existing page or provided mock up.

Adding the recommendations client script to your webpage will automatically inject a minimal set of styles onto your page. These styles will only reference areas in the page that are rendered by the client.

Retrieving Recommendations

When requesting recommendations, you'll need to provide a CSS selector for the HTML element to render the recommendations component into.

In addition, you will also need to pass in a pod identifier to let the client know which pod configuration you would like to use. Pods can be configured on the customer dashboard and allow you to specify the type of strategy you would like to use for each pod.

/*
 * Request recommendations for the configured Home Page 1 pod
 */
recommendations.requestRecommendations('#homepage', 'home_page_1');

User related recommendations are used when you want to provide personalized recommendations to a user based on their entire view and purchase history.

/*
 * Request recommendations for the configured Item Page 1 pod
 * with a single product id
 */
recommendations.requestRecommendations('#product-page', 'item_page_1', {
  itemId: 'item_id'
});

/*
 * Request recommendations for the configured Item Page 1 pod
 * with multiple product ids
 */
recommendations.requestRecommendations('#product-page', 'item_page_1', {
  itemIds: ['item_id_1', 'item_id_2', 'item_id_3']
});

Product related recommendations are tied to a product and require an itemId or a list of itemIds to be passed in the options object.

Recommendations that are product related are best used when you want to show alternatives to a particular item or set of items. For example, if a user is looking at a toothpaste, these recommendations can show other types of toothpaste.

It also works well for showing items that a user would purchase in addition to a particular item or set of items. For example, if a user is looking at toothpaste, these recommendations can show toothbrushes and dental floss.

Responding to Events

/*
 * The client has made a request for recommendations.
 */
recommendations.on('request.recommendations', function(requestInfo) {
  const { maxResults, podId, itemId, selector } = requestInfo;
});

/*
 * The client has received and is displaying results.
 */
recommendations.on('received.recommendations', function(response, info) {
  const { results, total_num_results } = response;
  const { maxResults, podId, itemId, selector } = info;
  ga('send', 'event', 'recommendations', 'loaded', response.total_num_results);
});

/*
 * The user has clicked on a recommendation.  If this event has no handlers,
 * the client will automatically send users to the URL of the associated result.
 */
recommendations.on('clicked.recommendation', function(event, info) {
  event.stopPropagation();
  event.preventDefault();

  const { index, recommendation, podId, selector } = info;
  window.location = recommendation.data.url;
});

When a user interacts with the recommendations client or when Constructor.io services communicate with the recommendations client, the client emits its own events that the page can hook into. Here are a list of the events available and the data that they send.

Note that all events are optional, but that for some events if there are no handlers the recommendations client will handle the event in a sensible manner.

Configuring UI Options

var options = {
  uiOptions: {
    pods: {
      item_page_1: {
        maxResults: 4,
        renderError: () => {},
        renderLoading: () => {},
        renderRecommendationHeader: () => {},,
        renderRecommendation: () => {},
      },
      item_page_2: {
        maxResults: 4,
        renderError: () => {},
        renderLoading: () => {},,
        renderRecommendationHeader: () => {},,
        renderRecommendation: () => {},
      },
      home_page_1: {
        maxResults: 5,
        renderError: () => {},
        renderLoading: () => {},
        renderRecommendationHeader: () => {},
        renderRecommendation: () => {},
      },
      cart_page_1: {
        maxResults: 5,
        renderError: () => {},
        renderLoading: () => {},
        renderRecommendationHeader: () => {},
        renderRecommendation: () => {},
      },
    },
  },
};

/*
 * Create the client with new options
 */
var recommendations = new ConstructorioSearch.Recommendations(options);

There are a few options for the recommendations client and every option is optional. If an option is missing then the recommendations client does not render that component. On the right is a comprehensive list of the current options we support.

Note that all rendering functions must return either a React Component or an HTML string. If a renderer returns an HTML string it will be run through a sanitizer before rendering for security reasons.

Additionally, all rendering functions take a single argument, props, of type object. The individual keys on that object vary by rendering function.

If any option is incorrectly configured for the client, a warning will show up in the JavaScript console and that option will be ignored.

Disposing a Client

/*
 * Dispose of the client and clean up all event listeners
 */
recommendations.dispose();

Disposing the client will clean up all the listeners and HTML elements that were attached to the page.