Recommendations

Recommendations is the feature intended for improving user interaction with client’s service by personalization. Its main purpose is to offer items from catalog to the user according to client’s preferences.

Use-cases

for e-commerce, newspapers, etc.:

  • section with latest articles or recently added items to stock on homepage
  • “most read articles”, “popular items” section on homepage
  • section with similar or “bought together” products on product page or in the cart
  • email campaign with personalised offer (regular or for reactivation of user)

Models

Content-based

Recommends items based on similarity of attributes. Select required and optional attributes which will be considered for measuring the similarity. Required fields have to match all, match in optional fields will be preferred (these items will be put first) but items without these fields can be returned. Select the minimum number of optional attributes which have to match.

Preferences of many users

Select at least 1 event with attribute containing item identification for training. You can select up to 5 events if you want to capture broader usage of your site, e.g. events for item view and for purchase. It is also possible to filter these events to target more specific audience. Events of all users from the specified time range will be used for training a model. Click train to start building a model. The training can take a while. Model will be automatically updated after training.

Note: This type of recommendation utilizes collaborative filtering algorithm and sometimes it’s references as such.

Manual selection

Cherry-pick the items that you want to promote by their item ID.

New on stock

New items from the catalog. Select which attribute will be used for filtering.

Previously seen items

Items the user has interacted with in the past and we can offer them again. Select type of event which describes this interaction (typically a purchase) and date interval to pick these events from. You can also set order in which the events (and items in them) will be considered. Possible options are: by frequency – items found more times are preferred (items user buys often), or order by time of event – newer first or older first.

Chosen by metric

Select an event attribute identifying the item, then define a metric specifying how well this item performs. You can use this engine to recommend items with the most purchases, that brought the most revenue or fulfill any other goal (highest metric value is best). Note that the calculation is subject to a 5 minute cache.

Requirements

 

When using model utilizing events in configuration, make sure that IDs used in these events are the same as IDs in catalog (item_id) that is linked with one model.

For example: when model “Preferences of many users” is trained on event purchase_item with attribute product_id then ensure that selected catalog contains primary key (item_id) that matches purchase_item.product_id.

Configuration

You can find Recommendations section under Campaigns -> Recommendations. The process is as follows:

  1. Select catalog to use for recommendations
  2. Select model
  3. Select combination strategy

Implementation

Website

After your recommendation model is ready, you can use Exponea SDK and call getRecommendation method or use REST API directly (API docs not covered here).

Basic snippet

<div id="recommendations">
    Preparing recommendations just for you...
</div>
<script>
    var options = {
        // Required parameters:
        recommendationId: "RECOMMENDATIONS ID HERE",
        callback: onRecommendationsLoaded,
        // Optional parameters:
        //size: 10, // Specifies upper limit of the recommendations to return. Defaults to 10.
        //anti: false, // Returns items most surprising to the customer. `similarity`, `anti` and `anonymous` are mutually exclusive. Defaults to false.
        //similarity: false, // Tries to find similar items regardless of customer, based on provided items. `similarity`, `anti` and `anonymous` are mutually exclusive. Defaults to false.
        //anonymous: false, // Tries to find similar items regardless of customer. `similarity`, `anti` and `anonymous` are mutually exclusive. Defaults to false.
        //consider_known_items: false, // If true, include items that the customer has interacted with in the past. Defaults to false.
        //items: [item_id], // Required if `similarity` is true. Maps item id to its weight. For example: {"items": {"the_item": 1, "other_item": 4.7}}
        //strategy: "winner", // If specified, overrides the predefined value of the recommendation. Corresponds to the setting in the application. Can be one of "winner" or "mix".
    };
    exponea.getRecommendation(options);

    // render loaded items
    function onRecommendationsLoaded(data) {
        // check if enough items are loaded ...
        if (data && data.length > 0) {
            var element = document.getElementById('recommendations'); // recommendations target element
            // rendering...
            var ul = document.createElement('ul');
            element.appendChild(ul);
            for (var i = 0; i < data.length; i++) {
                var item = data[i];
                var li = document.createElement('li'),
                    a = document.createElement('a');
                a.id = item.item_id;
                a.setAttribute('href', item.url);
                a.innerText = a.textContent = item.title;
                li.appendChild(a);
                ul.appendChild(li);
            }
        } else {
            // ... keep default items or print funny message
            document.getElementById('recommendations').innerHTML =
                'Nothing could be recommended for you!';
        }
    }
</script>

Event tracking

For evaluation purposes you should implement also event tracking

Tracking with AB test

Snippet below demonstrates following:

  • AB test
  • load recommendations using timeout
  • tracking
    • event recommendation action=show when recommended items are loaded
    • event recommendation action=timeout when loading times out (1000ms)
    • event recommendation action=click when item is clicked (track every time, on both recommended and default items)
var PLACEMENT = "homepage";
// get variant for AB test
exponea.getAbTest("rcm_" + PLACEMENT, {
    "Variant A": 50,
    "Control Group": 50
}, function (variant) {
    if (variant == "Variant A") {
        var RCM_STATUS = 0;
        // render items when loaded
        var onRecommendationsLoaded = function (data) {
            if (RCM_STATUS !== "TIMED_OUT") {
                RCM_STATUS = "LOADED";
                // track event recommendation action=show
                exponea.track("recommendation", {
                    action: "show",
                    variant: variant,
                    item_ids: itemIds,
                    // other required properties: placement, recommendation_id, ...
                });
                // render items ...
                // add click listeners ...
                // track event recommendation action=click when item is clicked
                exponea.track("recommendation", {
                    action: "click",
                    variant: variant,
                    item_id: itemId,
                    // other required properties: placement, recommendation_id, ...
                });
            }
        };

        // start loading recommendations
        var options = {
            recommendationId: "RECOMMENDATION ID HERE",
            callback: onRecommendationsLoaded,
            // ... add optional parameters as required by your use case, ie item_id, size, ...
        };
        exponea.getRecommendations(options);

        // start timeout to discard rendering when recommendations are loaded too late
        setTimeout(function () {
            if (RCM_STATUS !== "LOADED") {
                RCM_STATUS = "TIMED_OUT";
                // track event recommendation action=timeout
                exponea.track("recommendation", {
                    action: "timeout",
                    variant: variant,
                    // other required properties: placement, recommendation_id, ...
                });
            }
        }, 1000);
    } else if (variant == "Control Group") {
        // track event recommendation action=show
        exponea.track("recommendation", {
            action: "show",
            variant: variant,
            // other required properties: placement, recommendation_id, ...
        });
        // add click listeners to fallback items ...
        // track event recommendation action=click when item is clicked
        exponea.track("recommendation", {
            action: "click",
            variant: variant,
            item_id: itemId,
            // other required properties: placement, recommendation_id, ...
        });
    }
});

Required event structure

Event name Trigger Property name Description Data type Example
recommendation recommendation loading times out recommendation_id ID of recommendation model String 590b121683043403ab2de9eb
action action performed, in this case “timeout” String timeout
variant AB test variant name String Variant A
placement Visual placement of recommended items String “homepage” | “product” | “cart” | …
recommendation recommendation is rendered recommendation_id ID of recommendation model String 590b121683043403ab2de9eb
action action performed, in this case “show” String show
item_ids IDs of items recommended List of strings [“1”, “2”, “3”]
variant AB test variant name String Variant A
placement Visual placement of recommended items String “homepage” | “product” | “cart” | …
recommendation rcm item is clicked on website recommendation_id ID of recommendation model String 590b121683043403ab2de9eb
engine_name name of engine for clicked recommended item String up_sale_121212
action action performed, in this case “click” String click
item_id ID of clicked item String “1”
variant AB test variant name String Variant A
placement Visual placement of recommended items String “homepage” | “product” | “cart” | …