Retrieve On-Site Recommendations

Inserting Boomtrain recommendations into your shop is done using JavaScript callback functions. For each widget, you setup a callback function that will be called when the recommended products are received from the Boomtrain server.

Setting up the callback function

The syntax for setting up a callback function is the following:

// Boomtrain callback setup for WIDGET_ID
var _btcommerce = _btcommerce || [];
_btcommerce.push(['_req_widget_callback', WIDGET_ID, options, callback_function]);

The parameters are to be set as described in the following table:

ParameterDescription
WIDGET_IDThe identifier of the widget for which recommendations are generated.
optionsA JavaScript object with these fields:
_items_cnt - number of recommended items
_params - additional parameters for the widget (necessary for multi-purpose widgets).

_params is optional and by default can be left empty, as the widget will draw its context from the page URL or JavaScript tracking. One case of using widget parameters is multi-currecy scenarios where you can add the currency as parameter in order to retrieve the product recommendations together with their prices in the specified currency.
callback_functionThe JavaScript callback function that is executed when the recommendations are received from the server

Retrieving the recommendations

The callback function receives two parameters: err and recommendation_response.

If the recommendations were generated without errors, err will be null and you will find the recommendations in the recommendation_response object. If there were errors generating the recommendations the error details will be available in the err object.

recommendation_response is an object that contains the recommended items and has the following structure:

{
  items: 
  [
    { // first recommended item
      item_code: "123", // product code
      other_attr: "attr value", // other optional attribute
    },
    { // second recommended item
      item_code: "456", // product code
      other_attr: "attr value", // other optional attribute
    }, 
    //...
  ],

  global: 
  {     
    title: "Most popular this week", // widget title (optional)
    other_attr: "value" // other optional attribute
    // ...
  }
}

Sample Code

The following snippet shows how to setup a Boomtrain widget and the callback function that renders the recommended products:

var _btcommerce = _btcommerce || [];
_btcommerce.push(
  ['_req_widget_callback',
  'WIDGET_ID', // Widget ID provided in the table below
  {'_items_cnt': 15, // Desired number of recommended products
  '_params': ['cat1','Perfumes','gender','Female','currency','USD']}, // Example for a category level 1, gender, and (all) currency filtered widget
  function (err, recommendation_response) 
  {
    if (err) 
    {  alert("Error in response from Boomtrain. Please check the console");
     console.log("Boomtrain recommendation_response error", err);
    } 
    else 
    {
      var arrIDs = []; // Array of Product IDs to populate
      for (var i = 0; i < recommendation_response.items.length; i++) 
      {
        arrIDs.push(recommendation_response.items[i]["item_id"]);
      }
    // debug output
    console.log("arrIDs", arrIDs); 
  }
}]);