Skip to main content


Optimizely Knowledge Base

Get started with Optimizely Web Recommendations

  • Show visitors content or products they may be interested in, based on their browsing behaviors
  • Choose the best algorithm for your recommendations
  • Test and iterate on your recommendations
  • Measure the impact of your Recommendations campaign

Optimizely Adaptive Recommendations makes it easy to add recommendations to any page on your site and measure the impact with Stats Engine. You can introduce visitors to products and content based on the algorithm you choose, and measure results.

  • Not sure if this stuff below should be folded into this article? It's from, which I am redirecting here because it seems pretty superfluous at this point. 

  • Here's what you can do with Recommendations:


    Experiment with multiple recommendations (layouts, algorithms, headers, placement) at the same time

    Fold recommendations into other visual changes that you test in your experiments

    Create Recommendations campaigns

    Set traffic allocation for a campaign to show a certain percentage of visitors the original variation or the variation with recommendations

    Target your campaigns to desktop or mobile visitors

    Modify the algorithm, layout, placement, and header text of your recommendations

    Measure the impact on your Results page and segment by mobile and desktop visitors

  • Automate recommendations with algorithms for hands-off ROI

  • Use Personalization to take manual control of messaging for bigger audiences or special promotions

  • Target recommendations to specific audiences, available with Personalization

  • Configure different recommendations (layout, algorithm, headers, placement) for specific audiences and deliver them with Personalization

  • Use the functionality that Personalization offers for managing, running, and analyzing campaigns

However, before you jump into building your first recommendations experiment, there are a couple of tasks you'll need to take care of first. This article walks you through: 

  • The pre-setup process;

  • Creating a catalog and a recommender for your experiment;

  • Configuring the Recommendations algorithm and deciding where it will display;

  • Previewing and verifying your results.

Read on for more details.


Before you can start using with Optimizely Adaptive Recommendations, you'll need to be in touch with your Customer Success Manager. They'll help with the initial setup and with getting you set up with the services bundle you'll need:

  • Recommendations platform training

  • Recommendations extension training

  • Recommendations experiment strategy training

  • Design & build a recommendations experiment test plan

  • Build & launch a recommendation experiment or campaign

  • Custom results review

  • Project management oversight

  • Build & configure an extension for recommendations (optional)

These trainings should take about 30 hours to complete. After that, you'll be ready to build your own recommendations experiments and campaigns.

Create a catalog

Your recommendation experiment will need a list of items to recommend to your visitors. These items are stored in a catalog. When you create a recommendations experiment, Optimizely will ask you to assign a catalog to it, so you'll have to create that first.

What goes into a catalog? That depends on your business. If you're running a retail site, this might be all the items you sell. For B2B companies, this might be a list of blog posts or help articles.

To build a catalog, follow these steps:

  1. Navigate to Implementation > Catalogs and click the Create New Catalog button.


  1. The New Catalog modal appears. Give your catalog a name and enter a description.

  2. Add the events and related tags you want to include in this catalog in the Catalog Events box.



Recommendations uses tags to determine which fields from your catalog will be displayed. You should create a tag for each of those fields in this step.

  1. Once you’ve added all the events to your new catalog, click Create Catalog.

  2. To download a CSV copy of your catalog, or to archive it, click the … button for the catalog you’re interested in. It will take at least 24 hours for Optimizely to assemble it for download.


When you create your catalog, Optimizely runs a validation check to ensure the items listed in it are still active. You may need to whitelist the user agent “Optimizely Recommendations” to allow this validation check to occur; otherwise, Optimizely will assume none of the items in your catalog are accessible. For this reason, you should turn off validation completely if your site is behind a login.

If your site uses custom pricing for each customer, do not collect any field that may appear differently to different users viewing the same item. Otherwise, the catalog will show inconsistent information for these items.

If you have questions about this, contact customer support.

Select the appropriate menu item and follow the prompts.

Set up a recommender

In addition to a catalog, your recommendation experiment will need a recommender, which is the combination of logic, filters and user inputs that tells Optimizely what items from your catalog it should recommend.

You should already have set up your catalog in a previous step. To set up a recommender, follow these steps:

  1. Navigate to Implementation > Recommenders and click the Create new Recommender button.

  2. The New Recommender modal will appear. Name your new recommender and type in a description.

Make sure the name you give your recommender is unique, since all your recommenders—even the ones you created for other catalogs—will appear next to each other when it comes time to select one for your experiment.

  1. Select the catalog you want this recommender to use from the Catalog drop-down menu. The recommender will not automatically use all the events contained in the catalog; instead, you'll attach specific events to this recommender to use in a later step.

Once you’ve selected a catalog for your recommender, you cannot change it to a different catalog. If you want to do that, you’ll have to start over by creating a new recommender.

  1. Select an algorithm for your new recommender to use from the Algorithm drop-down. Optimizely gives you four algorithms to choose from.


  1. Choose the specific catalog events you want to use as inputs to your algorithm.

  2. If the algorithm supports boost events, add the ones you want in the Boost Events box.

  3. Optionally, you can add a filter to further customize your recommender. To learn how to create one, just click here.

You can change the algorithm after you've set up the recommender. However, doing so will remove all your events and filters, and you’ll have to start over.

  1. When you're done configuring your recommender, click Create Recommender.

  2. To create an extension to display your recommendations, or to archive your recommender, click the … button next to the recommender's name. Select the appropriate menu item and follow the prompts.



Create a filter

Optimizely gives you the ability to add powerful filters to your recommenders. When you include a filter, Optimizely will apply it to any catalog items returned by the algorithm. Items that don't meet the filter conditions are not included in the recommendation's results.

This section provides a description of how to use the Filters interface to build a new filter from within the New Recommender modal. 


  1. Decide whether you want your recommender’s default behavior to be exclusive or inclusive. “Default behavior” in this case describes what the recommender will do if you don’t add any filtering conditions to it. For example, if you were to check the Exclude all recommendations by default box and then not include any conditions, your recommender would return no results: its default behavior was set to exclude all results, and it did exactly that. Likewise, if you were to leave the box unchecked without adding any conditions, you’d get a list of every item in your catalog.

    Your filtering conditions will determine which results appear or are excluded from your recommendations; you’ll set those up in the following steps.

  2. Decide whether you want this filter to include specific items or to exclude them, and make your selection here.

  3. If you are building a filter with multiple conditions, specify whether you want it to apply to items that meet all the conditions you set out, or if it should apply to items that meet any of the conditions.

  4. Here, you can select the values you want the filter to evaluate. These values will reflect the names of the fields on your items in the catalog, which in turn are acquired from the tags. Choose from any of the values listed, or add a custom value not included in that list.


If you select custom, you can type in any literal fixed value.


If you choose a tag instead, you can also choose which item the tag refers to. Key item is the page the visitor is viewing, while recommendation item is the item returned by your recommender.


This only applies when you are using the co-buy or co-browse algorithms. The collaborative filtering and popular algorithms do not support the use of a key item, so this drop-down will not appear in those cases.

  1. Select the comparison operator your condition will use. Do you want these values to be equal to each other? Should one be larger than the other?

  2. This allows you to add another row of conditions to your filter.


How this row is used by your filter depends on your selection in step 3. If you chose any, it means that only one of the condition rows must evaluate as true in order to return a match. If you chose all, then both (or however many conditions you end up adding) must evaluate as true in order to return a match.

  1. The Add condition group button will add an entirely new condition group to your filter.


The condition groups are evaluated in order looking for a match. If there are no matches, then the recommender takes the default action specified in step 1.

When you're done building your filter, return to step 8 in the Set up a recommender process above.

Preview your results

Once you have a recommender set up, you can preview the results it will generate before creating your experiment. If those results aren't what you expected, you can just refine the recommender until the results are correct.

Changes to filters or algorithms are not immediately visible. Your results may take up to 24 hours to update.

To preview your results, follow these steps:

  1. Navigate to Implementation > Recommenders and find the recommender you’re interested in. Then click the Previewer button; the Recommender Previewer will appear.



At the top, you'll see a set of summary statistics for your site's traffic over the last seven days:

  • Partial recommendations, which are items that have fewer than ten recommendations, usually due to missing data

  • Full recommendations, which are items that have a full set of 20 recommendations each 

  • Total recommended items, which is the number of rows of recommendations calculated when the algorithm was last run

  1. In the Preview Item Recommendations box, enter an ItemID to preview the other items that will be recommended to your visitors when they “view” that item. Note that this is most useful for algorithms that make recommendations based on items the visitor has already viewed. For context-free algorithms—like Popular, for example—changing the ItemID will not change the output, because the output in this case is not tied to any specific item.

Recommendation algorithms

When you set up your recommendations, you can choose from one of four algorithms:

Algorithm name

Use case



This algorithm tends to recommend items similar to those a visitor has recently viewed. For example, if a visitor has viewed several different tables during the current session, the algorithm is likely to recommend other tables.

"Visitors who viewed this product also viewed these other products."


This algorithm works well for recommending complementary products to those a visitor has previously viewed. For example, if a visitor has viewed a table, this algorithm may recommend chairs to go with it.

"Visitors who bought this product also bought these other products."

Collaborative filtering

This algorithm serves recommendations based on the combined browsing history of the user and other similar users. This is often shown as “Recommended for You.”
Items recommended by this algorithm will differ for each person, but will remain constant for the duration of any individual user’s viewing experience.

"You browsed similar products as this group of website visitors, and they tended to like these products."


This algorithm helps showcase crowd favorites on the homepage. Use it to introduce best-selling items to new visitors.

"Items that other visitors viewed or bought most often."

Recommendations are generated every 24 hours, so the catalog information may be up to 24 hours out of date.

Keep in mind that the co-browse algorithm is sensitive to the order in which items have been viewed, while the co-buy algorithm is not; instead, it only asks if the items have been viewed by the same person.

Types of algorithms
A recommendations algorithm will always produce an ordered list of (item, relevancy_strength) pairs. These lists usually contain 20 results. All Optimizely’s recommendation algorithms use the collective behavior of past visitors to arrive at their results. However, the input to each type of algorithm is different:
  • A visitor-based algorithm only cares about the visitor ID and will recommend based on each visitor’s specific viewing history. The results will be the same no matter which page the visitor is on; however, the recommendations will be generated specifically for each individual visitor. Examples are the recently-viewed and collaborative filtering algorithms. 
  • An item-based algorithm is only interested in the page the visitor is currently viewing. Results will be the same for each visitor, but should vary from item to item. These are typically described as “similar items” or “people who liked this also liked”. Examples are the co-buy and co-browse algorithms.
  • A global algorithm doesn’t care about either the current visitor or the current page. These typically appear on high-level pages (for example, the home page) where they are described as “our most popular options” or “check out these best sellers”. It can be a great place for new Recommendations users to start, but since the results are not personalized, it may not be appropriate for all applications. Examples include the popularity algorithm, which displays items in descending order of views, clicks, purchases, or whichever event you are using for your recommender.
Think of the input as a key to look up a recommendations output—the visitor-based algorithm will take a visitor ID as the input key, while an item-based algorithm will use the item ID. The global algorithm won’t need a key at all.
Similarly, the output can be thought of as the target. In an item-based recommender, both the key and target will be item IDs; in a visitor-based recommender, the key would be a visitorID and the target would be an item ID.
When you experiment and compare algorithms to each other, it only makes sense to compare apples to apples. It would be pointless to compare a co-browse algorithm to a popularity algorithm because they use completely different information. A more useful approach to experimentation would be adjusting the input events and the post filters.
Glossary of Recommendations terms
While you're probably familiar with most of the concepts and techniques used by Recommendations—like filters, algorithms, and unique IDs—there are a few that aren't referenced by any other Optimizely feature and may be new to you:
  • Catalog: The collection of all items that can appear in your visitors' recommendations. 
  • Events: Optimizely uses visitor events, such as product page views, to construct the catalog. Additionally, events are used to generate the recommendations, serving as the signal used to score the different items in relation to the user or to other items.
  • Item: Any unique product, piece of content, or other entity that can be recommended to your visitors, as well as all relevant metadata associated with it. For retail customers, items almost always correspond to specific products, but items can also be a website or URL in other contexts. Items are based on unique IDs; any catalog listings that share a unique ID are, by definition, the same item. Different pages may have different sets of tags and represent different item types.
  • Recommender: A combination of:
    • an algorithm,
    • the specific inputs to that algorithm, and
    • any business logic filters to be applied. 
Recommenders essentially take input from your visitors, run it through the algorithm and filters, and output a set of recommendations that are then displayed for your visitors.