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 .

👍

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

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]

🚧

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.

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:

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.

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

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.

🚧

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.

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:

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.

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

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.

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

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.

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

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:

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.

3. Blacklist already bought items.

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

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:

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.

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

4. Blacklist already bought items.

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

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.

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.

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.

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

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

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:

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.

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.

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.

2. Map the purchase event.

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

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.

4. Blacklist.

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

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.

2. Map the view event.

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

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.

4. Blacklist.

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

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