API Reference

Multiple Widgets

1. Multiple widgets on the same pageview: illustration

You need to register all the widgets that you wish to render. Let’s say your two widget names are "bottom-widget" and "trending-widget". You need to follow the same steps as for a single widget, except that you need to do it for each widget.

Step 1 Add recommendation unit placeholders for each widget.

<div id="li-bottom-recommendation-unit"></div>
<div id="li-trending-recommendation-unit"></div>

Step 2 Add mustache templates for each of your widgets

<script type="application/mustache"
        id="li-bottom-recommendation-template">
  {{#items}}
  <div class='recommended_item'>
    <a href="{{url}}">
      <img src="{{thumbnail}}" width="150" height="150" />
      <span class="title">{{title}}</span>
    </a>
  </div>
 {{/items}}
</script>

<script type="application/mustache"
        id="li-trending-recommendation-template">
  {{#items}}
  <div class='recommended_item'>
    <a href="{{url}}">
      <img src="{{thumbnail}}" width="150" height="150" />
      <span class="title">{{title}}</span>
    </a> by {{author}}
  </div>
 {{/items}}
</script>

Step 3

// Register calls for different widgets.
$p('register', {
	max: 6, // Number of items you want to show
	widget: 'bottom-widget',
	opts : {},
	callback: function(resp) {
    // Query selector should match div name from Step 1
		var el = document.querySelector('#li-bottom-recommendation-unit');
    // Template should match mustache template name from Step 2
		var template = document.querySelector('#li-bottom-recommendation-template').innerHTML;
    // Basically Mustache.render(template, resp);
		el.innerHTML = $p('render', template, resp);
    // Remove in production
    console.log("Debug was set to true; disable it in production!"); 
		$p('track', {
			elements: document.querySelectorAll('#li-bottom-recommendation-unit > div.recommended_item'), 
      // Match widget name
      name: 'bottom-widget',
      // Source "LI" indicates recommendations are provided
			// by LiftIgniter
			source: 'LI',
      // Optional parameters to track with each event.
      // If the corresponding 'register' call had optional
      // fields, exactly those fields MUST be present here.
			opts: {},
			_debug : true
    });
  }
});

$p('register', {
	max: 4, // Number of items you want to show
  widget: 'trending-widget',
	opts : {},
  callback: function(resp) {
    // Query selector should match div name from Step 1
		var el = document.querySelector('#li-trending-recommendation-unit');
		// Template should match mustache template name from Step 2
    var template = document.querySelector('#li-trending-recommendation-template').innerHTML;
    // Basically Mustache.render(template, resp);
		el.innerHTML = $p('render', template, resp);
    console.log("Debug was set to true; disable it in production!"); // Remove in production
		$p('track', {
      // Div name from Step 1 and recommendation item div name from Step 2
			elements: document.querySelectorAll('#li-trending-recommendation-unit > div.recommended_item'), 
      // Match widget name
      name: 'trending-widget',
      // Source "LI" indicates recommendations are provided
			// by LiftIgniter
			source: 'LI',
      // Optional parameters to track with each event.
      // If the corresponding 'register' call had optional
      // fields, exactly those fields MUST be present here.
			opts: {},
			_debug : true
		});
	}
});

// Fetch recommendations and trigger callbacks for all registered.
$p('fetch');

📘

Fetching

The fetch function must be called exactly once after all calls have been registered. This way we can make sure there are no duplicate recommendations across widgets, and also reduce latency by combining http calls to the model server when possible.

📘

Multiple widget registration

A widget can be registered multiple times before the fetch. Each time a widget is registered, the previous registration is overwritten. You will see a message in the Javascript console when you re-register a widget.

2. Priority between widgets, deduplication, and number of recommendations per widget

If you are showing multiple widgets on the same page, the priority between the widgets is determined by the order in which you register the widgets. If a particular widget is more important to you (i.e., you want to show better recommendations for it) be sure to register it first.

If you have multiple widgets, it is particularly important that you request only as many recommendations per widget as you need for that widget. Otherwise, the deduplication might lead us to discard quality recommendations.

3. Request Extra Fields

We allow only one set of fields across all widgets. Thus, if you need different fields across different widgets, you should fetch all fields that are needed for any of the widgets you are registering.

Note that we do not return fields for inventory items if we do not have those field values for those inventory items.

4. Trigger different widgets in different contexts

You might have different widget names for different user contexts. A typical use case is that your site has different layouts for desktop, mobile, and tablet, and you have different sets of active widgets for these contexts. For instance, you may have both a bottom widget and a trending widget in desktop, but only a bottom widget in mobile.

Please make sure to only register the widgets that are active in the context, so that the recommendations you fetch are the very best (if you register additional widgets that aren’t being used, you might end up getting poorer-quality recommendations on the widgets you do show because of deduplication).