Scenario defines a particular application of recommendations at your website, your mobile app or emailing campaign. It can be for example homepage, watch-next, cart or emailing-after-purchase.
You can set different behavior of the recommendations for each scenario and then monitor the performance of the scenarios in the KPI section.
Setting up a Scenario#
Create scenario in the Admin UI
- Go to the Scenarios section and click Create scenario.
- You need to set a name of the scenario and choose the recommendation endpoint which will be used in the scenario.
Set scenario parameter in the recommendation requests or create a HTML Widget
In case of using the API:
- Pass the name of the created scenario to scenario parameter of the recommendation request
- Example for scenario
client.send(new recombee.RecommendItemsToUser(userId, count,
result = client.send(RecommendItemsToUser(user_id, count,
result = client.send(RecommendItemsToUser.new(userId, count,
'scenario' => 'homepage'
RecommendationResponse result = client.send(
new RecommendItemsToUser(userId, count).setScenario("homepage")
var recombee = require('recombee-api-client');
var rqs = recombee.requests;
client.send(new rqs.RecommendItemsToUser(userId, count,
$result = $client->send(new RecommendItemsToUser($user_id, $count,
'scenario' => 'homepage'
RecommendationResponse result = client.Send(
RecommendItemsToUser(userId, count, scenario: "homepage")
Not sure which scenarios will work the best in your use case? See the Integration Tips.
Scenario settings in the Admin UI#
You can customize each of your scenarios.
Logic specifies the desired behavior of the recommendation model.
If you want to change the Logic in Admin UI, but logic parameter is already sent in the API requests and you are not a programmer, you can enable Override logic API parameter to use your settings from Admin UI.
Filters allow you to specify which items can be recommended in this scenario. You can pick some rules from Recombee library or your own Business Rules.
An item can be recommended only as long as all the filter rules applied to the scenario are satisfied.
If you specify a
filter as API parameter of the recommendation request, the filters from Admin UI will be combined with the filer specified in the request using the
Boosters allow you to prefer some items in this scenario in order to fulfill your business goals. You can pick some rules from Recombee library or your own Business Rules.
Each booster rule produces a number when evaluated for an item. The final boosting score for an item is computed as product of these scores from individual booster rules.
If you specify a
booster as API parameter of the recommendation request, the boosters from Admin UI will be combined with the filer specified in the request using the
Constraints allow you to configure how items with shared conditions may repeat within the recommendation results.
For example, you may want to recommend:
- At most 2 items from each category
- or at most 50 % of items from a single genre
- or just a single product per a parent product ID
In order to do that, you first need to create an Item Segmentation that describes the shared condition. This may be as simple as choosing one of the item properties - e.g. the category, however, it also enables you to express much more advanced rules.
When you have the Item Segmentation ready, you can add the Constraint to your Scenario and choose how many items per individual Segment (particular category, genre, etc.) can appear in the recommendation result.
- Absolute: Sets the maximal number of items from a single Segment
in the returned recommendations
- e.g. at most 3 items from a single brand
- Percentage: Sets the maximal portion of returned recommendations
that comprise of items from a single Segment
- e.g. at most 25 % from a single brand
In the case of the Absolute limit type, the given maximum count of items per Segment is by default applied to all the recommended items.
However, you may apply it only to smaller parts of the results by setting the window size.
For example, if you set the maximum count of items per Segment to 2 and the window size to 4, then within each consecutive 4 items in the recommendations at most 2 can be from a single Segment.
If you want to apply some Filters or Boosters to all of your Scenarios, you can put them to Global Settings - for example, you may always want to filter out the items that are not currently available.
By putting rules to Global Settings you ensure that these rules are always applied and you don’t need to worry about forgetting them when adding a new Scenario.
There is a Recombee library of generally useful filter and booster rules that can be applied to your scenarios. You can for example allow only items in stock or items from a particular category to be recommended, or boost recent items.
Beside these out-of-the-box rules, you can define your completely custom rules using our flexible ReQL language.
You can also let our AI ReQL Code Assistent generate the rule for you, based on your natural language input.
For example you can create a filter rule that allows only short (<30 minutes) movies in English to be recommended:
If you have multiple scenarios, and you want to recommend movies of a different length in each of them, you can make the maximal runtime an input value - parameter of the rule.
When you then apply this rule to a scenario, you can specify the maximal allowed runtime in minutes: