Integration of Recommendations

Requesting Recommendations

In order to get recommendations, you need to use the suggested getRecommendation() method from the JavaScript SDK library or directly use our REST API
The code for requesting product recommendations using Javascript SDK could be found in Web Deployment part of each of the recommendation engines in Exponea.
The full specification of the request can be found in our personalization guide, but below we describe the three most important parts attributes:

Key
Value
Description
Example

recommendationId
(Required)

String

Engine ID of an existing recommendation model. This ID is created when the engine is saved in Exponea.

'5a7c4dfefb6009323d4c7311'

fillWithRandom

Boolean

If true and there are not enough recommended items by the model, Exponea fills the gap with random items from the catalog until the required size is reached.

'true'

size

Integer
(Default value: 10)

Number of recommended items to return.
The maximum suggested size to use is 100.

'50'

items

Object

Information about currently viewed product by the browsing user. Represented as dictionary
'product_id: weight.'
Please use only single item in the dictionary with weight = 1.

'{'item_123': 1} '

catalogFilter

Array of Objects

Dynamically adds additional constraints to the template's catalog filter (first step when setting recommendations engine) when retrieving recommended items

'{[
{
property: "category_2",
constraint: {
type: "string",
operator: "contains",
operands: [{ type: "constant", value: "shoes" }]
}
}
]}'

categoryNames
(Required for Metric based category and Personalized category page engines)

Array
(Max size: 10)

Currently viewed category or categories by the browsing user.

['shoes', 'high heels']

Integration to campaigns

Here we present two Jinja code snippets in order to demonstrate how to integrate recommender engines into campaigns. We will demonstrate one simple and one advanced usage with an example engine ID 5a7c4dfefb6009323d4c7311. Properties of retrieved items can be later obtained by calling {{ item.<attribute> }} convention.

<ul id="recommendations">
    {% for item in recommendations('5a7c4dfefb6009323d4c7311') %}
        <li>
            <a href="{{ item.url }}">{{ item.title }}</a>
        </li>
    {% endfor %}
</ul>

The above snippet processes obtained recommendations (=10 items) from the engine 5a7c4dfefb6009323d4c7311 and integrates them into HTML.

<ul id="recommendations">
    {% for item in recommendations('5a7c4dfefb6009323d4c7311', 
        fill_with_random = "true",
        size = 50,
        items = {"item_123": 1},
        category_names = ["shoes", "men"], # use only for Category type of models
        catalog_filter = [{
            property: "category_2",
            constraint: {
                type: "string",
                operator: "contains",
                operands: [{ 
                    type: "constant", 
                    value: "shoes" 
                }]
            }
        }]
    ) %}
        <li>
            <a href="{{ item.url }}">{{ item.title }}</a>
        </li>
    {% endfor %}
</ul>

This snippet calls 50 products including a context item item_123 in the request taht are already filtered down by category_2 contains "shoes" rule. If the recommendation model cannot return enough products, fill_with_random = true wil fill the gap with randomly selected products that match the catalog filter conditions.

For further information see Personalization in Jinja section.

How to evaluate product recommendations?

It is suggested to compute metrics revenue per visitor and click-through rate using Reports. It is good practice to carry out an AB test, either with your current model or if you do not have any, with any other model from Exponea. To learn how to set up the report, see our guide to AB Test Basic Evaluation. In order to track recommendation-attributed revenue, please implement event tracking for clicking on any product which was generated by Exponea product recommendations.

Event tracking for revenue attributed to recommendations

For evaluation purposes, it is needed to implement event tracking for product purchases, product views, and clicks on recommended products.
The snippet below demonstrates the following:

  • AB test
  • Load recommendations using a 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 an item is clicked (track every time, on both recommended and default items)

Don't forget to insert your recommendation_id in the code. See how to find the ID.


var PLACEMENT = "homepage";

// get variant for AB test
exponea.getAbTest("rcm_" + PLACEMENT, {
    "Variant A": 50,        // Recommendations from Exponea
    "Control Group": 50     // Default baseline
}, 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 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 properties: placement, recommendation_id, ...
                });
            }
        };

        // start loading recommendations
        var options = {
            recommendationId: "RECOMMENDATION ID HERE",
            callback: onRecommendationsLoaded,
            // ... add optional parameters as required by your use case, i.e. item_id, size
          // categoryNames in case of Metric based category engine & Personalized category page engine
        };
        exponea.getRecommendation(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 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 properties: placement, recommendation_id, ...
        });
    }
});

Integration of Recommendations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.