# Scenarios > Source: https://docs.recombee.com/scenarios > For the complete documentation index, see [llms.txt](/llms.txt). **Table of contents** * [Setting Up a Scenario](#setting-up-a-scenario) * [Requesting a Scenario](#requesting-a-scenario) * [Scenario Settings in the Admin UI](#scenarios-in-admin-ui) * [Logic](#logic) * [Filters](#filters) * [Global Settings](#scenarios-in-admin-ui-global-settings) * [Boosters](#boosters) * [Constraints](#constraints) * [Limit Type](#limit-type) * [Window Size](#window-size) * [Composite Recommendations](#composite-recommendations) * [Examples](#examples) * [Because You Watched ](#because-you-watched-movie-) * [Articles from ](#articles-from-category-) * [Artists Related to ](#artists-related-to-artist-) * [Fully Personalized Homepage](#fully-personalized-homepage) * [Structure](#structure) * [Setup Mode](#setup-mode) * [Templates](#templates) * [Custom](#custom) * [Configuration](#configuration) * [A/B Testing](#ab-testing) * [Setting Up an Experiment](#ab-testing-setup) * [Metrics](#ab-testing-setup-metrics) * [Variants](#ab-testing-setup-variants) * [Report](#ab-testing-report) # Scenarios **Scenario** defines a specific application of recommendations on your website, mobile app, or email campaign. For example, you might create scenarios such as _homepage_, _watch-next_,_cart_, or _emailing-after-purchase_. You can configure different recommendation behaviors for each scenario and then monitor their performance in the[KPI section](/admin_ui#admin-ui-database-sections) and the [Insights](/insights). ## Setting Up a Scenario In the Recombee **[Admin UI](https://admin.recombee.com)**, navigate to the **[Scenarios](/scenarios)** section. Choose **Create Scenario** and enter a name for your new scenario. [![Create scenario](/img/gui/create_scenario.png)](/img/gui/create_scenario.png) Then, select its **Type**: [![Create scenario](/img/scenarios/ranked-list-vs-composite.png)](/img/scenarios/ranked-list-vs-composite.png) **Ranked List** * Returns a single set of recommended **items**, **users**, or **[Item Segments](/segmentations)**. * Ideal for typical [recommendation](/api#recommendations) and [search](/api#search) use cases. **Composite** * Suitable for cases such as _Because You Watched _ or _Items from for You_. * Produces a composite response with two parts: * **Source** — a single item, user, or [Item Segment](/segmentations) * **Result** — a set of recommended items, users, or [Item Segments](/segmentations) related to the _Source_ * See [Composite Recommendations](#composite-recommendations) for more details. ## Requesting a Scenario Use the Scenario in [API Requests](/getting_started#getting-started-recomms) or [No-Code Widgets](/no-code-widgets). When using the API: * Pass the name of the created scenario to the `scenario` parameter of the recommendation request. * Example for scenario `homepage`: ```js const result = await client.send( new recombee.RecommendItemsToUser(userId, count, { scenario: 'homepage', }) ); ``` Tip Not sure which scenarios are best for your use case? See our [Integration Tips](/integration_tips). ## Scenario Settings in the Admin UI You can customize each scenario individually. [![Setting Logic & Filter in the Admin UI](/img/gui/setting_scenario.webp)](/img/gui/setting_scenario.webp) Setting Logic & Filter in the Admin UI ### Logic [Logic](/recommendation_logics) defines the **behavior of the recommendation model**. [![Setting Logic in the Admin UI](/img/gui/set_logic.png)](/img/gui/set_logic.png) ### Filters Filters determine **which items can be recommended** in this scenario. You can select filters from the Recombee library or create your own [Business Rules](/reql#business-rules). An item can be recommended only if all filter rules assigned to the scenario are satisfied. Tip If you specify a `filter` as an [API parameter](/api#recommend-items-to-user-param-filter), the filters from the Admin UI will be combined with it using the `AND` operator. [![Set filter](/img/gui/set_filter.png)](/img/gui/set_filter.png) #### Global Settings To apply filters to all scenarios, use **Global Settings**—for example, to always exclude unavailable items. [Rules](/reql#business-rules) defined in Global Settings are applied automatically to all scenarios, ensuring consistency across your application. [![This Filter rule is applied to all Scenarios](/img/gui/global_settings.png)](/img/gui/global_settings.png) This Filter rule is applied to all Scenarios ### Boosters Boosters allow you to **prioritize certain items** within a scenario to support your business goals. You can use predefined booster rules or create your own [Business Rules](/reql#business-rules). Each booster rule produces a numeric score for each item. The final boosting score is the product of the scores from all applied booster rules. Tip If you specify a `booster` as an [API parameter](/api#recommend-items-to-user-param-booster), it will be combined with the Admin UI boosters using the `*` operator. [![Set booster](/img/gui/set_booster.png)](/img/gui/set_booster.png) ### Constraints Constraints define **how frequently items sharing certain conditions can appear** in recommendation results. Examples: * At most 2 items per category * No more than 50% of items from a single genre * Only one product per parent product ID To use constraints, first create an [Item Segmentation](/segmentations) that represents the shared condition (e.g., category, genre, or brand). Then, add the constraint to your scenario and set how many items per segment are allowed in the recommendations. [![Constraints in Admin UI](/img/gui/constraints.png)](/img/gui/constraints.png) #### Limit Type * **Absolute** — sets a fixed number of items per segment (e.g., max 3 per brand). * **Percentage** — sets a proportion (e.g., max 25% from one brand). #### Window Size When using the **Absolute** limit type, the limit applies to all recommended items by default. To apply it to smaller groups, set a **window size**. For example, with a max of 2 items per segment and a window size of 4, each consecutive group of 4 recommendations will contain at most 2 from the same segment. ![](/img/gui/constraints_window_size.svg) ## Composite Recommendations Composite Recommendations return both a _source entity_ (e.g., an Item or [Item Segment](/segmentations)) and a related list of recommendations in a single response. They are requested via the **[Composite Recommendation API endpoint](/api#composite-recommendation)**. ### Examples #### Because You Watched * _Source_: The movie (Item) watched by the user * _Result_: Movies related to the watched one [![Because You Watched Example](/img/gui/composite_because_you_watched.png)](/img/gui/composite_because_you_watched.png) Tip Check out the Because You Watched [Scenario Recipe](/recipes/video/fully-personalized-homepage/because-you-watched) for more info #### Articles from * _Source_: The user’s favorite category ([Item Segment](/segmentations)) * _Result_: Recommended articles from that category [![Articles from Category Example](/img/gui/composite_items_from_category.png)](/img/gui/composite_items_from_category.png) #### Artists Related to * _Source_: The user’s favorite artist ([Item Segment](/segmentations)) * _Result_: Recommended artists related to the favorite artist [![Related Artists Example](/img/gui/composite_artists_to_artist.png)](/img/gui/composite_artists_to_artist.png) #### Fully Personalized Homepage Often, multiple _Composite Recommendations_ are requested in a [Batch](https://docs.recombee.com/api#batch) to fully personalize the homepage or other sections of a website or app. For example, to display five rows on the homepage — each representing one of the user’s **top five categories** and showing the most relevant content within that category — you can send **five Composite Recommendation requests** in a single Batch, set as: * _Source:_ category (_[Item Segment](/segmentations)_) * _Result:_ content (_Items_) This approach enables the homepage to consist of dynamically personalized sections. The API automatically ensures that five distinct categories are returned in the response, avoiding duplicates. See the [API code example](/api#composite-recommendation-example-category-sections-with-reordering) for implementation details. Tip Check out the Fully Personalized Homepage Scenario Recipes for: * [Video](/recipes/video/fully-personalized-homepage/personalized-re-ordering-of-rows-advanced) * [News](/recipes/news/homepage/personalized-sections-with-reordering) * [E-Commerce](/recipes/e-commerce/fully-personalized-homepage/personalized-re-ordering-of-sections-advanced) ### Structure Composite Recommendations can be viewed as two sequential requests: 1. Recommend the _Source_. 2. Recommend the _Result_ for that _Source_. For instance, _Articles from _ involves: * [Recommend Item Segments To User](/api#recommend-items-to-user) to find the category. * [Recommend Items To Item Segment](/api#recommend-items-to-item-segment) to get articles from that category. Each _Composite Recommendation_ counts as **one API request** for billing. ### Setup Mode When creating a _Composite Recommendation_ scenario, you can choose a **Template** or a **Custom** configuration. #### Templates Predefined templates are available for common cases such as _Because You Purchased_ or _Videos From Top Genre For You_. Templates define both the [endpoints](#structure) used for each stage and the [Logic](/recommendation_logics). #### Custom Custom configuration allows you to manually define the endpoints for each stage and assign different [Logics](/recommendation_logics) as needed. ### Configuration In the Admin UI, you can set distinct [Filters](#filters) and [Boosters](#boosters) for each stage (_Source_ and _Result_). You can also specify these settings using the [sourceSettings](/api#composite-recommendation-param-sourceSettings) and [resultSettings](/api#composite-recommendation-param-resultSettings) API parameters. ## A/B Testing A/B Testing lets you compare different recommendation configurations within a Scenario and measure their effect on your key metrics. Each experiment runs on top of a specific Scenario, with traffic split between a **Control** (the current Scenario configuration) and one or more **Variants**. ### Setting Up an Experiment You can create an experiment either from the **A/B Testing** tab inside a Scenario's detail view, or from the standalone **A/B Testing** section in the Admin UI. When creating an experiment, provide a title (or leave it blank to have one generated automatically), then select the **Scenario** it should run on. Set the **start date** — and optionally an **end date** — to define the experiment's time window. [![Create Experiment form](/img/ab_testing/ab_testing_create.png)](/img/ab_testing/ab_testing_create.png) #### Metrics Metrics define what you want to measure. You must choose at least one metric before the experiment can be created. Recombee provides a **library of predefined metrics** organized by vertical (Video, E-Commerce, Articles & News, etc.) — including metrics such as _Conversion Rate_, _Click-Through Rate (CTR)_, _Watch Time from Recommendations_, and _Income from Recommendations_. [![Choose Metrics panel](/img/ab_testing/ab_testing_choose_metrics.png)](/img/ab_testing/ab_testing_choose_metrics.png) You can also create **custom metrics** based on [Insights](/insights). A custom metric lets you specify a data source (e.g., _Detail Views from Recommendations_) and apply filters — for example, to track views from recommendations only for items from a particular category, or to measure the purchase rate exclusively for items above a certain price threshold. #### Variants Each experiment has a **Control** — the Scenario's current configuration — and one or more **Variants** that modify it. When creating a Variant, you can change any combination of: * **Logic** — the whole recommendation model ensemble or its individual parameters * **Filters** — which items are eligible to be recommended * **Boosters** — how items are ranked within results * **Constraints** — limits on how frequently certain [Segment of items](/segmentations) appear The Admin UI clearly shows what has been changed in each Variant relative to the Control. [![Create Variant panel](/img/ab_testing/ab_testing_create_variant.png)](/img/ab_testing/ab_testing_create_variant.png) Once Variants are defined, assign a **traffic allocation** (percentage) to each using the sliders. Use the **lock icon** to fix a Variant's allocation so it is not affected when adjusting others. Click **Distribute Evenly** to split traffic equally across all Variants. [![Variants allocation sliders](/img/ab_testing/ab_testing_variants_allocation.png)](/img/ab_testing/ab_testing_variants_allocation.png) The sliders always add up to 100%, so changing one row moves the others. A row you have typed a percentage into is locked automatically, which keeps that value from being redistributed away when you adjust another Variant — click its lock icon to release it. [![Adjusting variant traffic allocation with the sliders, explicit percentages and the lock](/img/ab_testing/ab_testing_variant_ratios.webp)](/img/ab_testing/ab_testing_variant_ratios.webp) ### Report The report shows the effect of each Variant on every selected metric, including whether the results are **statistically significant**. For each metric, the table displays: * **Users** — number of users in the Variant and their share of total traffic * **Improvement** — change relative to the Control baseline * **Probability to be best** — likelihood that this Variant outperforms all others * **Probability to beat baseline** — likelihood that this Variant outperforms the Control * **Distribution** — the mean and variance of the metric's value across users The best-performing Variant is highlighted in the results. [![A/B Testing results report](/img/ab_testing/ab_testing_report.png)](/img/ab_testing/ab_testing_report.png)