Return Recommendations Real-time Filter Data

In your API campaigns, real-time filters enable real-time results based on data obtained within the session. For example, show products priced higher than the currently-viewed product or present products based on the user's explicit selection.

Common use cases

Free shipping suggestions: Recommended products that fall in the price range that qualifies the user to get free shipping (over the threshold).
Upsell: Recommended products that are priced higher than the currently viewed product.
Product finder: Recommended products based on explicit filters set by the visitor in the session (for example, gift finder wizard).
Explicit user property: Recommended products that match a user property known in the session (gender or location).

Limitations

Up to 30 custom-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 2048, and the evaluated value length limit is 255.

Parameters

id: Client-side API only. The unique ID number for every rule. This ID is used in the API response (if 2 rules have the same ID, the second rule is dropped).
type: Include/exclude only.
slots: All or specific slot positions where the first slot is in position 0.
conditions: Condition types for filtering recommendations include:
- 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
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 are given priority over any existing filters (built-in).
For client-side API only: Add priority data and set a priority between 0 and 29. If there are existing rules defined in Experience OS (regular or real-time, any rule type), this lowers their existing priorities.

When you build the rule, multiple arguments inside the same condition use the OR operator between them, whereas if you add additional conditions inside a rule, they use the AND operator.

Example: AND operator

{
   "user":{
     "dyid": "3337168279039708439",
     "dyid_server":"3337168279039708439"
 },
 "session":{
   "dy":"dy_session1000000000010"
 },
 "context":{
  "page":{
    "type":"HOMEPAGE",
    "location":"https://website.com/",
    "data":[]
   }
 },
 "options":{
   "isImplicitPageview": true,
   "recsProductData": {
       "fieldFilter": [
           "categories"
        ]
      }
 },
 "selector":{
   "names":[
     "test_rcom"
   ],
    "args":{
    "test_rcom":{
      "realtimeRules":[
        {
          "type":"include",
          "slots":[],
          "query":{
            "conditions":[
              {
                "field":"categories",
                "arguments":[
                 {
                   "action":"CONTAINS",
                   "value":"basketball"
                 }
              ]
           }, 
           {
                "field":"categories",
                "arguments":[
                {
                   "action":"CONTAINS",
                   "value":"football"
                }
              ]
            }
          ]
        }
      }
    ]
  }
 }
 },
   "device":{
       "userAgent":"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
       "ip":"54.100.200.255"
   }
}

Example: OR operator

...

"selector":{
    "names":[
       "test_rcom"
     ],
     "args":{
     "test_rcom":{
      "realtimeRules":[
        {
           "type":"include",
           "slots":[],
           "query":{
             "conditions":[
                 {
                   "field":"categories",
                   "arguments":[
                   { 
                      "action":"IS",
                      "value":"basketball"
                   }, 
                   {
                       action":"IS",
                      "value":"football"
                   }, 
                  ]
                }
......

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 the free shipping threshold and cart total and price < free shipping threshold (50 in this case).

Code sample: Client-side API

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);
  });
}

Code sample: Server-side API

ample: Server-side API
{
    "user": {
        "id": "yaexono4ohphania" //for WEB mode use "dyid"
    },
    "session": {
        "custom": "iquahngaishe2koh" //for WEB mode use "dy"
    },
    "selector": {
        "names": [
            "recs campaign"
        ],
        "args": {
            "recs campaign": { //The campaign the rule will be applayed on
                "realtimeRules": [
                    {
                        "type": "include", // Include or exclude
                        "slots": [], // Position in widget
                        "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
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            }
        }
    },
    "context": {
        "page": {
            "type": "CART",
            "data": [
                "7383723-010"
            ],
            "location": "https://example.org",
            "locale": "en_US"
        },
        "device": {
            "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
            "ip": "54.100.200.255"
        },
        "pageAttributes": {
            "customPageAttribute": "someValue"
        },
        "options": {
            "isImplicitPageview": true
        }
    },
    "options": {}
}

Use case 2: Build a product finder

Use to request 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.

Code sample: Client-side API

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);
  });
}

Code sample: Server-side API

{
    "user": {
        "id": "yaexono4ohphania" //for WEB mode use "dyid"
    },
    "session": {
        "custom": "iquahngaishe2koh" //for WEB mode use "dy"
    },
    "selector": {
        "names": [
            "recs campaign"
        ],
        "args": {
            "recs campaign": { //the campaign the rule will be applied on
                "realtimeRules": [
                    {
                        "type": "include", // Include or exclude
                        "slots": [
                            1,
                            2,
                            3
                        ], // Position in widget
                        "query": {
                            "conditions": [
                                {
                                    "field": "categories", // Condition
                                    "arguments": [
                                        {
                                            "action": "IS", // Action type IS / IS_NOT / CONTAINS / EQ / GT / GTE / LT / LTE
                                            "value": categoryName // Value of condition
                                        }
                                    ]
                                }
                            ]
                        }
                    }
                ]
            }
        }
    },
    "context": {
        "page": {
            "type": "CART",
            "data": [
                "7383723-010"
            ],
            "location": "https://example.org",
            "locale": "en_US"
        },
        "device": {
            "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36",
            "ip": "54.100.200.255"
        },
        "pageAttributes": {
            "customPageAttribute": "someValue"
        },
        "options": {
            "isImplicitPageview": true
        }
    },
    "options": {}
}