Recommendations Client-Side APIs

You can use Dynamic Yield’s recommendation engine to return the results of a recommendation without Dynamic Yield rendering it using a client-side API. This lets you control how to display the recommendation instead of serving the recommendation in the HTML with a Recommendation campaign. The results are returned as a set of products in JSON format.

Serving Recommendations via Client-Side API

Create a Strategy to Call via API

1. Go to Assets › Strategies
2. Create a recommendation strategy, and turn on the "Use via an API call (advanced)" toggle in the Strategy settings.
   
3. Choose the number of items you would like the API to return (usually, the number of items you plan to render).
4. Save the strategy.
5. In the "Recommendation Strategies" list - click the more options menu on the row of the recommendation strategy you'd like to use.
6. Choose "Embed Code" and copy the API snippet.
   
7. Edit the recommendationWidgetData API as required. For details, see below. You can also use this API in addition to the Return Recommendation real-time Filter Data API to add real-time filter rules to filter the results based on data obtained within the session. 
8. Paste the code into a Custom Code campaign to execute it for the relevant users.
9. Implement click the performance of the recommendations using the recommendations.registerElements API. For details, see below.

Render Recommendation or Dynamic Content 

Render the Dynamic Content or Recommendation defined by a name or id. This is only applicable for campaigns whose Location is determined by "Embed code":

Syntax

DYO.smartObject(smartObjectId, props)

Parameters:

• smartObjectId: Id or name of the Dynamic Content or Recommendation
• props:
  rendering properties:
  target – selector id used as rendered tag target
  afterRenderCallback – an optional function to execute after the item is rendered

Example:

DYO.smartObject('Car Ad', {
  target: 'car_ad_div_id',
  inline: true
});

Return Recommendation Widget Data

Use Dynamic Yield’s recommendation engine to return the results of a recommendation without Dynamic Yield rendering it using a client-side API.

This lets you control:

1. How to display the recommendation
2. Adding real-time filters to enable real-time results based on data obtained within the session (e.g. show products priced higher than the currently viewed product, present products based on the visitors explicit selection, etc.)

The results are returned as a set of products in JSON format. For more details, see Recommendations API – Client-Side. This API also requires you to track the recommendation widget as detailed below.

Syntax

DYO.recommendationWidgetData(id, opts, callback) 

Parameters:

• id: The ID of the strategy to use when rendering the recommendation.
• opts: Optional parameters
  • context: The page context is taken from the current page unless you specify a different context here.
  • maxProducts: Overrides the “number of items” value from the Strategy configuration screen.
  • exclude: An array of SKUs or Group_IDs to exclude from the recommendation results. This is often used to prevent displaying the same item more than once on a page that has multiple recommendation widgets. (This option is not available for the recently viewed strategy which doesn't use this item removal function)
  • realtimeRules: Add real-time filter rules in order to enable real-time results based on data obtained within the session. Use-case and real time filter data information can be found in Return Recommendation Realtime Filter Data below. 
• callback: Callback function to execute once recommendation data is returned.

Example Call:

// pass product context manually to request
DYO.recommendationWidgetData(12345, {
      exclude: {
      'group_id': ['127829', '1217317', '1247581']
      },
      context: {
        'lng': 'en_GB',
        'type': 'PRODUCT',
        'data': ["1253851-001"]
      }},
      function(err, data) {
        if (err) {
 
          //error handling 
        }
        var rcomData = data;
      });

Example Response:

 
{
  "wId": 3197,
  "name": "TOP_N", // strategy mame
  "expData": {
    "varId": null,
    "expId": null
  },
  "fId": 543,
  "fallback": true, //at least one of the items used a fallback
  "slots": [
    {
      "item": {
        "entity_id": "330367",
        "color": "1349",
        "product_url": "......html",
        "color_prod_img": "https:.....3.jpg",
        "publish_time": "2019-07-05T03:22:08",
        "flag_img_url": "NONE",
        "size_label": "38",
        "color_image": "https://tropicalflowerdress.......jpg",
        "size": "1899",
        "category": "dresses",
        "related_colors_label": "string",
        "title": "great flower dress",
        "related_colors": "619,628,3064,3070,3133",
        "color_label": "flower",
        "item_group_id": "620",
        "category1": "women",
        "sku": "6510120",
        "description": "the best tropical flower dress in the universe",
        "price": 199,
        "in_stock": true,
        "categories": [
          "women",
          "dresses"
        ],
        "dy_display_price": "199",
        "name": "tropical flower dress",
        "url": "https://www.tropicdresses........html",
        "category4": "",
        "flag": "",
        "tier_prices": "NONE",
        "thumbnail_url": "https://tropicdresses......jpg",
        "image_url": "https://tropicdresses......jpg",
        "keywords": [
          "women",
          "dresses",
              ],
        "group_id": "33112327",
        "quantity": "2"
      },
      "fallback": true, //this item used a fallback strategy
      "strId": 1,
      "md": {}
    },
    {
      "item": {
        "entity_id": "330368",
        "color": "1349",
        "product_url": "......html",
        "color_prod_img": "https:.....4.jpg",
        "publish_time": "2019-07-06T03:21:00",
        "flag_img_url": "NONE",
        "size_label": "38",
        "color_image": "https://tropicalflowerpants.......jpg",
        "size": "1899",
        "category": "pants",
        "related_colors_label": "string",
        "title": "great flower pants",
        "related_colors": "619,628,3064,3070,3133",
        "color_label": "flower",
        "item_group_id": "534",
        "category1": "women",
        "sku": "6510145",
        "description": "the best tropical flower pants in the universe",
        "price": 89,
        "in_stock": true,
        "categories": [
          "women",
          "pants"
        ],
        "dy_display_price": "89",
        "name": "tropical flower pants",
        "url": "https://www.tropicpants........html",
        "category5": "",
        "flag": "",
        "tier_prices": "NONE",
        "thumbnail_url": "https://tropicpants......jpg",
        "image_url": "https://tropicpants......jpg",
        "keywords": [
          "women",
          "pants",
              ],
        "group_id": "33112347",
        "quantity": "1"
      },
      "fallback": false, //this item used the chosen strategy
      "strId": 1,
      "md": {}
    },
  ]
}

Return Recommendation Real-time Filter Data

Real-time filters are used in order to enable real-time results based on data obtained within the session (e.g. show products priced higher than the currently viewed product, present products based on the visitor's explicit selection, etc.).

Limitations:

• Up to 30 customer filter rules per widget.
• Up to 5 real-time rules per widget (out of the 30 custom filter rules in all).
• Each rule can have up to 10 conditions\arguments.
• Rule string size limit is 1024, and the evaluated value length limit is 255.

Parameters:

• id: Unique ID number for every rule. This id will be used for APIs response. (If there are 2 rules that have the same id, the second rule will be dropped) 
• type: Include\exclude only 
• slots: All or specific slot positions where the first slot is in position 0
• conditions: 
  • IS // string or boolean (‘In stock’ - true/false) only 
  • IS_NOT // string only
  • CONTAINS // Up to 10 of this type per filter 
  • EQ, GT, GTE, LT, LTE // numbers only
• Conditions are used to define condition type for filtering recommendations. Condition types:
• Building conditions - When building the rule, inside an argument multiple conditions have ‘or’ operator between them and adding additional arguments will have ‘and’ operator.
• value: Parameter for filter value by condition. Regular-expressions are not supported for real-time filters (can and should be added as additional conditions to the filter)
• priority (optional): The real-time filters will be given first priority above any existing filters (build in DY Admin). But If you choose to add priority this can be done by adding priority data and choosing priority between 0 and 29. If there are existing rules defined in Admin (regular or real-time, any rule type) this will lower their existing priority 

Use Case #1 - Adding free shipping suggestions

Request recommended products that fall in the price range that would qualify the visitor to get free-shipping (pass the threshold). In this example, the free shipping threshold is 50 and we would like to recommend products that price > difference between free shipping threshold and cart total and price < free shipping threshold (50 in this case).

var THRESHOLD = 50; // Cart threshold 
var CART_TOTAL_SELECTOR = '.js-cart-totals__total' // Cart selector per site
var STRATEGY_ID = 64040; // Strategy ID for recommendations
 
var cartValuePromise = DYO.waitForElementAsync(CART_TOTAL_SELECTOR).then(function(elements) {
  return parseFloat(elements[0].textContent.replace(/[^\d.-]/g, ''))
});
 
cartValuePromise.then(function(cartValue) {
  var freeShippingRemainder = THRESHOLD - cartValue;
 
  if (freeShippingRemainder > 0) {
    console.log('Products above', freeShippingRemainder);
    getProducts(STRATEGY_ID, freeShippingRemainder, THRESHOLD);
  } else {
    console.log('Over shipping limit')
    // no need for recs.
  }
});
 
function getProducts(strategyId, min, max) {
  var realtimeRules = [{
    "id": -1,
    "query": {
      "conditions": [{
        "field": "price", // Condition
        "arguments": [{
          "action": "GTE", // Action type IS / IS_NOT / CONTAINS / EQ / GT / GTE / LT / LTE 
          "value": min // Value of condition
        }]
      }, {
        "field": "price", // Condition
        "arguments": [{
          "action": "LTE",
          "value": max
        }]
      }]
    },
    "type": "include", // Include or exclude
    "slots": [] // Position in widget
  }];
 
  DYO.recommendationWidgetData(strategyId, {maxProducts: 10, realtimeRules: realtimeRules}, function(err, data) {
    console.log(data);
  });
}

Use Case #2 - Build a Product finder for requesting recommended products based on explicit filters set by the visitor in the session. In this example we will trigger 3 slots (2, 3 and 4) of product recommendations from the category with the highest score based on the users affinity profile. 

var STRATEGY_ID = 12345;
 
DY.API('callback', function() {
  DY.ServerUtil.getUserAffinities(function(error, affinityObject) { 
    if (error || !affinityObject.categories) {
  	getProducts(STRATEGY_ID, null);
return;
    }
 
    var categories = affinityObject.categories;
    var sortedCategories = Object.keys(categories).map(function(name) {
      return {
        name: name,
        score: categories[name]
      };
    }).sort(function(a,b) {
      return b.score - a.score;
    });
 
    getProducts(STRATEGY_ID, sortedCategories[0].name);
  }, 5);
});
 
 
function getProducts(strategyId, categoryName) {
  var realtimeRules = [{
    "id": -2,
    "query": {
      "conditions": [{
        "field": "categories", // Condition
        "arguments": [{
          "action": "IS", // Action type IS / IS_NOT / CONTAINS / EQ / GT / GTE / LT / LTE 
          "value": categoryName // Value of condition
        }]
      }]
    },
    "type": "include", // Include or exclude
    "slots": [1, 2, 3] // Position in widget
  }];
 
  DYO.recommendationWidgetData(strategyId, {maxProducts: 10, realtimeRules: realtimeRules}, function(err, data) {
    console.log(data);
  });
}

Track Recommendation Widget

In order to track a recommendation widget you manually added to your site using the recommendationWidgetData API (see above), you need to make sure Dynamic Yield can track the widget as well. The JSON results of recommendationWidgetData are used to configure this tracking.

Syntax

DYO.recommendations.registerElements(el); 

Usage

1. Add the following attributes to the DOM element that contains the recommendation widget:

       <div data-dy-widget-id="WIDGET_ID_HERE" data-dy-feed-id="FEED_ID_HERE">
           <div data-dy-product-id="PRODUCT_SKU_HERE" data-dy-strategy-id="STRATEGY_ID_HERE">...</div>
           <div data-dy-product-id="PRODUCT_SKU_HERE" data-dy-strategy-id="STRATEGY_ID_HERE">... </div>
           . .
         </div>
     
   

   • widget id – the wId from the JSON response. This is the ID of the strategy.
   • feed id – the fId from the JSON response.
   • strategy id – the strId from the JSON response (can be found under each "slot"). This represents the strategy type of each slot. 
   • product id – the sku of each product from the JSON response.

• Run the following API call:
  

  DYO.recommendations.registerElements(el);

  Where el is the DOM element with the widget ID attribute (data-dy-widget-id).

Show all Recommendation Widget Responses

Presents all products returned by all recommendation widgets on the page.

Syntax

DYO.recommendations.getLoadedWidgets()

Response is an array of Return Recommendation Widget Data results for all recommendation widgets returned on the page.