Setting up recommendation templates

This guide will walk you through the setup of the recommendations templates used in the use cases step by step.

To find the template you need, use the table of contents on your right :arrow-right+:.

To find out more

For reference on the individual models mean see Product Recommendation Templates

New items template

We will be working with this example catalog (Data & Assets -> Catalogs):

Product catalog with name “products” containing three columns: item_id as unique identifier of the product, date added as timestamp when the product was added to the catalog and stock availability as number of products on stock.

Product catalog with name “products” containing three columns: item_id as unique identifier of the product, date added as timestamp when the product was added to the catalog and stock availability as number of products on stock.

1. Choose a product catalog.

In this step, it is necessary to set a product catalog containing all your products and set a catalog filter to filter our only relevant products. Typically, it is used to filter only available products]

Example of choosing “products” as a product catalog and filtering of products at least with one in stock.

Example of choosing “products” as a product catalog and filtering of products at least with one in stock.

The product catalog needs to be imported before creating recommendations in Data&Assets -> Catalogs.

2. Choose the date column.

Choose column which represents date when an item has been added or updated in the catalog. This field must be part of the imported product catalog and it is not automatically created by Exponea. This column could be any numerical/datetime column and results will be sorted in descending order.

Example of column “date_added” which contains information about the date when the product was added to the catalog.

Example of column “date_added” which contains information about the date when the product was added to the catalog.

3. Leave optional sections (Blacklist, Customer Preferences) empty and save the model.

Additional options

Additional options are described in the Product Recommendations Manual

Integration process

Integration process on Homepage or to Campaigns is described in the Integration of Recommendations

Similar items template

Similar items template looks for alternative products based on their shared properties from the catalog. In this template, you can specify how exactly this matching should work.

In the following example, we will demonstrate the functionality of this template on a fashion client. This client wants to recommend most similar products to the item being currently viewed so that:

  • The gender will be consistent
  • The category will be consistent
  • If possible, the brand will be consistent
  • If possible, both or neither of the products will be on sale
  • Recommended products were not already bought by a given customer last 90 days
  • Optionally, the size of clothes will match the preferred size of the given customer

If the engine fails to recommended items under desired conditions, it will fall back into recommending random items. If you spot such behavior while testing it, please consider using the “Advanced template” with a simple combination strategy with other models such as previously seen items.

1. Choose a catalog.

In this step it is necessary to set a product catalog containing all your products and set a catalog filter in order to recommend only products on stock:

Example of picking product catalog + filtering based on stock

Example of picking product catalog + filtering based on stock

2. Specify required and optional attributes.

The second step is to choose the required and optional attributes that will be taken into consideration while matching alternative products. In our case, the required ones are gender, category and the optional ones are brand, on_sale.

Example of Required attributes picker

Example of Required attributes picker

The required attributes will be used as a necessary condition for matching products. The optional ones are preferred but not necessary.

Example of Optional attributes picker + overlap

Example of Optional attributes picker + overlap

Additionally, you can also specify the overlap size determining the minimum number of matches of the optional attributes. In this case, we require the optional match to be 1 = either the brand will be consistent or the on_sale tag will be consistent. Items with no match on brand or on_sale will be considered as irrelevant.

You can often set these settings too restrictive - thus resulting in bad performance. Always try to consider weaker conditions if the model performance is not sufficient.

3. Blacklist already bought items.

Add blacklisting to not show products that were already bought by a given customer in the past 3 months.

Example of Blacklist picker with 90 days window on purchases.

Example of Blacklist picker with 90 days window on purchases.

4. Set customer preferences.

In order to personalize, even more, we can reorder the recommendations by the preference of the customer. In this case, we are interested in showing products of the size that is consistent with the preferred size of the customer. This preferred size can be obtained from historical purchases.

Example of Customer Preferences picker reordering recommendations based on customer size.

Example of Customer Preferences picker reordering recommendations based on customer size.

Textual Similarity template

This model shows similar items to a given product based just on product descriptions. Therefore, the main requirement for the catalog is to have an up-to-date description of all products that you want to consider for recommendations. The higher the quality of product descriptions the better recommendations you can expect.

Similarly to example in Similar items, we will demonstrate the functionality of this template on a fashion client. This client has a catalog containing multiple columns describing their products, such as description itself but also colors and materials as well. The client’s goal is to recommend the most similar products to the item being currently viewed so that:

  • Category will be consistent to the currently viewed item
  • Brand will be consistent to the currently viewed item
  • The price of each recommended product should be higher than 15 EUR

If the engine fails to recommended items under desired conditions, it will fall back into recommending random items. If you spot such behavior while testing it, please consider using the “Advanced template” with a simple combination strategy with other models (e.g. previously seen items).

Disclaimer: This model is currently not available as a template. Therefore if you’re interested in using this model you should ask for it directly from the AI Recommendations team.

Here, you can implement the same logic as we described in the Similar items template except for the “required” and “optional” attributes logic.

Product Detail template

This model looks at historical sessions of customers browsing various products. We assume that customers use to browse similar products while searching for alternative products so we build a product representation based on these historical interactions. The advantage of this approach is that we can recommend alternative products even for customers with no historical data whatsoever.

1. Choose catalog.

In this step it is necessary to set a product catalog containing all your products and set a catalog filter in order to recommend only products on stock:

Example of picking product catalog + filtering based on stock

Example of picking product catalog + filtering based on stock

2. Specify target event.

In this step, specify the target event and some attributes based on which the model can create the product representation. We recommend using something natural such as the total price from the purchase events.

Example of target event picker set to total price of purchase events

Example of target event picker set to total price of purchase events

3. Blacklist already bought items.

Add blacklisting to not show products that were already bought by a given customer in the past 3 months.

Example of Blacklist picker with 90 days window on purchases.

Example of Blacklist picker with 90 days window on purchases.

Optionally, you can also set the customer preferences reordering. Check the “Alternative Products (based on items)” for an example.

Popular right now template

This model recommends products that are sorted according to a given metric. This metric is chosen as a count of events (most of the time purchases or views) and represents the popularity of products.

In the following example, we will demonstrate the functionality of this template on a fashion client. This client wants to recommend the most popular products on the homepage so that:

  • Popularity = view count in the last 90 days.
  • We will not recommend products already bought by a customer viewing these products.
  • If possible, prefer products of the brand that matches the preference of a customer

1. Choose a catalog.
In this step it is necessary to set a product catalog containing all your products and set a catalog filter in order to recommend only products on stock:

Example of picking product catalog + filtering based on stock

Example of picking product catalog + filtering based on stock

2. Specify the metric event.

In this step, specify the metric event so that the historical count reflects your representation of popularity. In practice, it’s usually calculated as a count of purchases (hot items) or a count of views (most trending items). In our case, we are picking the view_item.
While mapping the popularity metric, don’t forget to add the product ID identifier to the chosen event.

Example of event picker based on view_item.

Example of event picker based on view_item.

3. Set the learning window.

Set the historical timeframe relevant to the calculation of the metric event. In this case, we have defined the popularity for each item as “Count of views in the last 90 days”.

Example of calendar picker - last 90 days for learning window.

Example of calendar picker - last 90 days for learning window.

4. Blacklist already bought items.

Add blacklisting to not show products that were already bought by a given customer in the past 3 months.

Example of Blacklist picker with 90 days window on purchases.

Example of Blacklist picker with 90 days window on purchases.

5. Set customer preferences.

In order to personalize even more we can reorder the recommendations by the preference of the customer. In this case, we are interested in showing products made by a preferred brand of the customer. This preferred brand can be obtained from historical purchases.

Example of Customer Preferences picker reordering recommendations based on customer’s preferred brand.

Example of Customer Preferences picker reordering recommendations based on customer’s preferred brand.

Metric based category template

Engines set up using Metric based category recommendation template are best suited for placement on a category page. There are two prerequisites to leveraging this engine - correct data mapping and tracking of categories in events (see "Requirements" above).

The following case illustrates setting up an engine using this template for a client with a goal of showing the top-viewed items within the category that the customer is currently looking at.

1. Choose a catalog.

The first step is to choose the desired catalog which contains items to be displayed in recommendations.

Sometimes you do not want to recommend all items from your catalog. In such cases, you can choose to filter items based on their attributes located in the catalog. Since this engine will be used in the category page, it makes sense to show as many popular items as possible as long as these items are active.

Example of item filtering based on active column in the catalog.

Example of item filtering based on active column in the catalog.

2. Chose the catalog identifiers, time-frame and interaction event metric.
In this step, specify the event that corresponds to the desired historical interaction between customers and products. In our case, we will pick view_item. The logic is followed: for top-selling items pick purchase_item event, for top-viewed items pick view_item event, for the most often wished items pick add_to_wishlist event etc.

Specify two parameters for the selected event:

  • parameter corresponds to product ID (in our case product_id),
  • parameter corresponds to tracked categories (in our case category). It can be string or list of strings (see "Requirements" above).

The next step is the specification of the time-frame and interaction event metric. The logic for time-frame: if we want only top-selling products from the last month - select Lats 30 days, etc. The logic for event metric: for top-viewed items pick: count -> event -> "view_item" etc. (same logic as in reports).

Note, you need to choose a catalog item identifier to be equal to the item_id column in your catalog. If this step is not done properly, the engine won’t work as intended.

Example of mapping catalog identifiers and the count(view_item) as desired metric.

Example of mapping catalog identifiers and the count(view_item) as desired metric.

3. Blacklist - optional
Optionally, we can add blacklisting to not show items that were already bought by a given customer.

Example of Blacklist picker with 90 days window on views.

Example of Blacklist picker with 90 days window on views.

4. Set customer preferences - optional
In some special cases we can reorder the recommendations by the preference of the customer. In the case of "Metric based category" template, we don't suggest use this setting without consultation with our team (it can caused unexpected behavior of your engine).

Example of Customer Preferences.

Example of Customer Preferences.

5. correct recommendation integration
The step number five is the last step of the engine setup. Afterward, you can save your engine. However, this template requires one special attribute in recommendation integration - categoryNames (see technical manual). Attribute categoryNames determine categories for which the engine generates recommendation (e.g. currently viewed category).

The logic for selection of items from category/categories:
There are 4 ways for selecting the items. Each way uses different operator to select recommended items (operator from reports):

  • We track category as string & request single category in categoryNames attribute (e.g. in event view_item we track category: "t-shirt" & we call getRecommendation with categoryNames = ["t-shirt"]). Used operator: equals. The engine recommends all items where category equals to "t-shirt" (sorted based on event metric).
  • We track category as string & request list of categories in categoryNames attribute (e.g. in event view_item we track category: "t-shirt" & we call getRecommendation with categoryNames = ["t-shirt", "shirt"]). Used operator: in. The engine recommends all items where category in ["t-shirt", "shirt"].
  • We track category as list of strings & request single category in categoryNames attribute (e.g. in event view_item we track category: ["t-shirt", "woman", "short-sleeve"] & we call getRecommendation with categoryNames = ["t-shirt"]). Used operator: any item equals. The engine recommends all items where any item from category equals to "t-shirt".
  • We track category as list of strings & request list of categories in categoryNames attribute (e.g. in event view_item we track category: ["t-shirt", "woman", "short-sleeve"] & we call getRecommendation with categoryNames = ["t-shirt", "shirt"]). Used operator: any item in. The engine recommends all items where any item from category in ["t-shirt", "shirt"].

Additional options

Additional options are described in the recommendations documentation.

Customer recent interactions template

Customer recent interactions template offers a model best suited for reactivation campaigns with a goal of repeated purchases. This model does not require a large number of user interactions, just recent ones.

In the following example, we will demonstrate the functionality of this template on a fashion client. This client wants to recommend last viewed items using a targeted campaign in order to reactivate lost customers in the last 7 days.

1. Choose a catalog.
In this step it is necessary to set a product catalog containing all your products and set a catalog filter in order to recommend only products on stock:

Example of picking product catalog + filtering based on stock

Example of picking product catalog + filtering based on stock

2. Specify an interaction event.

In this step, specify the event that corresponds to the desired historical interaction between customers and products. In our case, we will pick view_item mapped on product ID.

Example of event picker based on view_item.

Example of event picker based on view_item.

3. Set the learning window.
Set the historical timeframe relevant to the last viewed items. In this case, we are picking last 7 days because we are interested only in customers who interacted with our products recently.

Example of calendar picker - last 7 days for learning window.

Example of calendar picker - last 7 days for learning window.

4. Optional section
Leave optional sections (Blacklist, Customer Preferences) empty and save the model.

Additional options

Additional options are described in the recommendations documentation.

Campaings integration

The integration process to Campaigns or other parts of the webpage is described in the (technical manual)[https://docs.exponea.com/docs/integration-of-recommendations].

Personalised recommendations for you

1. Choose a catalog.
In this step, it is necessary to set a product catalog containing all your products and set a catalog filter to filter our only relevant products. Typically, it is used to filter only available products.

2. Specify required events.

Set three required events based on which will be computed the similarity between customers. These three events are the Detail view event which refers to an event when a customer visits the detail page of a product, Add to cart event refers to an event when a customer adds anything to a cart and Purchase event refers to an event when customer purchase a product.

3. Optional events.

Here it is possible to set additional events that might indicate customer preference to a given product such as rating event or wishlist event. For the purpose of this example, we will leave it disabled.

4. step: Learning window.

In the next step, we will set the learning window. Data from this timeframe will be used for training the machine learning model. It is advised to use at least 3 months of past interactions if we use more data a recommendation model could find more useful patterns. However, if customer preferences are changing very rapidly it is advised to use a lower time period. If a customer has no interactions (interaction here is any event defined in step 2) in a given period, it is not possible to compute personalized recommendations and products with the most interactions (top products by the number of interactions) will be returned as a fallback.

5. Blacklist.

Add blacklisting not to show the products that were already bought by a particular customer in the past 3 months.

Customers who bought this item also bought Template

1. Choose a catalog.

In this step, it is necessary to set a product catalog containing all your products and set a catalog filter to filter our only relevant products. Typically, it is used to filter only available products.

Example of picking product catalog + filtering based on stock

Example of picking product catalog + filtering based on stock

2. Map the purchase event.

In this step, you need to map the purchases on product IDs.

Example of mapping

Example of mapping

3. Learning window.

The performance of the algorithm is heavily dependent on the number of historical co-purchases (more items bought together). Therefore we suggest using Lifetime learning window.

Example of learning window

Example of learning window

4. Blacklist.

Add blacklisting to not show the products that were already bought by a particular customer in the past 3 months.

Example of Blacklist.

Example of Blacklist.

Personalised category template

1. Choose a catalog.

In this step, it is necessary to set a product catalog containing all your products and set a catalog filter to filter our only relevant products. Typically, it is used to filter only available products.

2. Specify catalog details.

Specify catalog column that represents categories based on which our engine will generate the recommendations. Note that values in this column have to be the same values as categories send in categoryNames attribute in the recommendation request. The category column always contains string values. In the case of list-based categories, we use a string with delimiter - e.g. “t-shirt” or "t-shirt;blue;man” (see Requirements above & 8th step below). In the case of list-based categories specify a delimiter that separates individual categories (for "t-shirt;blue;man” it is “;”). If you don’t use list-based categories, keep this input empty.

3. Specify required events.
Set three required events: Detail view event, Add to cart event, Purchase event. Detail view event refers to an event when a customer visits detail page of a product, Add to cart event refers to an event when a customer adds anything to a cart and Purchase event refers to an event when a customer purchase a product.

4. Optional events.
Here it is possible to set additional event which should indicate customer preference to a given product - wishlist event. For the purpose of this example, we will leave it disabled.

5. Learning window.
In the next step, we will set the learning window. Data from this timeframe will be used for training the machine learning model. It is advised to use at least 3 months of past interactions if we use more data a recommendation model could find more useful patterns. However, if customer preferences are changing very rapidly it is advised to use a lower time period. If a customer has no interactions (interaction here is any event defined in step 3) in a given period, it is not possible to compute personalized recommendations and attractive products will be returned as a fallback (for more information see template documentation).

6.Blacklist - optional.
Optionally, we can add blacklisting to not show items that were already bought by a given customer.

7. Customer Preferences - optional.
In some special cases, we can reorder the recommendations by the preference of the customer. In the case of the "Personalized category page" template, we don't suggest using this setting without consultation with our team as it can sometimes cause unexpected behavior of your engine. For the purpose of this example, we will leave it disabled.

7th step is the last step of the engine setup. Now, you can save your engine.

8. Correct recommendation configuration
However, this template requires one special attribute in recommendation integration - categoryNames , for more info see technical manual. Attribute categoryNames determines categories for which the engine generates recommendations (e.g. currently viewed category).

The logic for selection of items from category/categories:
There are 4 ways that can happen. Each way uses different operators to select the recommended items.

  • Category column is string & request single category in categoryNames attribute (e.g. category column has value "t-shirt" & we call getRecommendation with categoryNames = ["t-shirt"]). Used operator: equals. The engine recommends all items where category column equals to "t-shirt" (with personalized ranking of items).
  • Category column is string & request list of categories in categoryNames attribute (e.g. category column has value "t-shirt" & we call getRecommendation with categoryNames = ["t-shirt", "shirt"]). Used operator: in. The engine recommends all items where value from category column in ["t-shirt", "shirt"].
  • Category column is string containing multiple categories separated by delimiter & request single category in categoryNames attribute (e.g. category column has value "t-shirt;woman;short-sleeve" & we call getRecommendation with categoryNames = ["t-shirt"]). Used operator: any item equals. The engine recommends all items where any item from category column equals to "t-shirt" (values in category column are split by delimiter “;”).
  • Category column is string containing multiple categories separated by delimiter & request list of categories in categoryNames attribute (e.g. category column has value "t-shirt;woman;short-sleeve" & we call getRecommendation with categoryNames = ["t-shirt", "shirt"]). Used operator: any item in. The engine recommends all items where any item from category column in ["t-shirt", "shirt"].

Updated 3 months ago

Setting up recommendation templates


Suggested Edits are limited on API Reference Pages

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