Setting Up Recommendation Templates

This guide will walk you through the setup of the recommendations templates which will be also used in the Recommendations Use Cases.

📘

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):

754

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]

609

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 Bloomreach Engagement. This column could be any numerical/datetime column and results will be sorted in descending order.

609

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

Textual Similarity template

This feature is currently available in Beta version

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

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 brand will be consistent
  • The category_level_1 will be consistent
  • If possible, the category_level_2 will be consistent
  • If possible, the category_level_3 will be consistent
  • Recommended products were not already bought by a given customer last 90 days

If the engine fails to recommend items under desired conditions, it will fall back into recommending items from the catalog that are still compliant with the provided exact and optional match filters, but they don't need to be necessarily based on the selected textual attributes. If the model even fails to recommend items using this first-layer fallback, 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:

1221

Example of picking product catalog + filtering based on stock

2. Specify exact match and optional attributes.

The second step is to choose the exact match and optional attributes that will be taken into consideration while matching alternative products. Only searchable catalog properties can be used. In our case, the exact match ones are category_level_1, brand and the optional ones are category_level_2, category_level_3.

1228

Example of Exact match attributes picker

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

1214

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 category_level_2 will be consistent or the category_level_3 will be consistent. Items with no match on category_level_2 or category_level_3 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. Specify textual attributes.

The third step is to choose the textual attributes based on which textual similarity of products will be computed. In our case, the textual attributes are title and description. Note, items will be ordered based on textual similarity that is computed through TF-IDF algorithm.

1208

Example of Textual attributes picker

🚧

Items with similarity lower than similarity threshold are filtered out. If items are too different, it is possible that engine will recommend less results than expected.

4. Blacklist already bought items.

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

1217

Example of Blacklist picker with 90 days window on purchases.

More Like This template

This model shows similar items to the reference item, such as one currently viewed by the customer, based on shared catalog properties. Therefore, the main requirement is to have all properties for products in your catalog that you want to consider for recommendations and to have them as searchables.

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 brand will be consistent
  • The category_level_1 will be consistent
  • If possible, the category_level_2 will be consistent
  • If possible, the category_level_3 will be consistent
  • Recommended products were not already bought by a given customer last 90 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:

1221

Example of picking product catalog + filtering based on stock

2. Specify exact match and optional attributes.

The second step is to choose the exact match and optional attributes that will be taken into consideration while matching alternative products. Only searchable catalog properties can be used. In our case, the exact match ones are category_level_1, brand and the optional ones are category_level_2, category_level_3.

1998

Example of Exact match attributes picker

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

1980

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 category_level_2 will be consistent or the category_level_3 will be consistent. Items with no match on category_level_2 or category_level_3 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.

1638

Example of Blacklist picker with 90 days window on purchases.

(4). Set Customer preferences (optional).

Additionally, you can also narrow down recommendations to individual preferences of your customers. This will result in matching recommendations being shown on top of the results for the specific customer.

1962

Customer preferences option

Filter Based template

This model shows randomly selected products that fulfill the criteria defined in the catalog filter according to your preferences of what you would like to present to your customers. You can recommend products based on catalog filters, such as items from a particular category, brand, with a certain price, or a combination of filters.The main requirement is to have an imported product catalog containing as many features as possible - like descriptions, tags, brands, categories, colors, etc.

In the following example, we will demonstrate the functionality of this template on a fashion client. This client wants to evenly promote products from Brand A that cost over 50 USD. This client also wants to make sure the recommended products were not already bought by a given customer in the last 90 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 that are:

  • on stock,
  • from Brand A,
  • cost over 50 USD.
1994

Example of picking product catalog + filtering based on your preferences.

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

2000

Example of Blacklist picker with 90 days window on purchases.

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:

609

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.

909

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.

687

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:

609

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.

522

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”.

840

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.

544

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.
If more customer preferences are used, products fitting the first condition are at the top of the list, then products fitting the second condition are just behind them, and so on. At the end, there are products that do not fit any of those conditions.

744

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 in the Template documentation).

The following case illustrates setting up an engine using this template for a client with the 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.

577

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 a string or list of strings (see Product discovery Use Cases).

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.

871

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.

848

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).

853

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:

609

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.

609

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.

560

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)[doc:integration-of-recommendations].

Personalized 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.

609

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.

853

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.

836

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.

544

Example of Blacklist.

Customers who viewed this item also viewed 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.

495

Example of picking product catalog + filtering based on availability

2. Map the view event.

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

796

Example of mapping

3. Learning window.

The performance of the algorithm is heavily dependent on the number of historical co-viewed item inside one session (more items bought together). Therefore we suggest using long enough learning window.

651

Example of learning window

4. Blacklist.

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

801

Example of Blacklist