HomeDev guideAPI ReferenceGraphQL
Dev guideUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Personalized Search & Navigation

Describes the native integration for Optimizely Search & Navigation, and how to work with search attributes and values provided with the search client to boost search hits.

Personalized Search & Navigation (formerly Personalized Find) is a personalization service you can add to Optimizely Search & Navigation as part of the Optimizely Personalization product suite.



Personalized Search & Navigation currently only works with Optimizely Customized Commerce.

Integration packages

In addition to Episerver.Find, these packages are needed for the integration:

  • EPiServer.Personalization.Commerce – Integration for product recommendations.
  • EPiServer.Find.Personalization – Search & Navigation integration components.

See the Personalization section for how to start with Personalized Search & Navigation.

Integration components

Personalized Search & Navigation fetches attributes from a personalization service containing a list including property name, property value, and boosting. The list is included as “boosting” with the Search & Navigation service when searching or filtering content.

The boosting changes the generated “score” on content, to make the result personalized. Depending on the query and what attributes return from the personalization service, this functionality will have a different impact on the result.


To enable retrieval of search attributes, configure the Attribute API. The required attributes are episerver:personalization.Site and episerver:personalization.ClientToken. See Optimizely Product Recommendations for information about configuring the Recommendations API.

Retrieve attributes

The Recommendations API must fetch attributes before executing a personalized Search & Navigation query and store or cache them for fast retrieval before the user needs them so that latency is not adversely affected when a site visitor executes a query or filter. The following sections describe how to retrieve attributes.

Call the Refresh method

Call the Refresh method on an instance of the EPiServer.Find.Personalization.IPersonalizationClient. To retrieve the active EPiServer.Find.Personalization.IPersonalizationClient instance, call the Personalization() extension on EPiServer.Find.Personalization.IClient.

using EPiServer.Find.Personalization;

namespace OptimizelySite.Controllers {
  public class MyController: PageController < MyPage > {
    private readonly IClient _client;
    public MyController(IClient client) {
      _client = client;
    public ActionResult Index(MyPage currentPage) {
      System.Threading.Tasks.Task.Factory.StartNew(currentContext => {
          System.Web.HttpContext.Current = (HttpContext) currentContext;
      return View(currentPage);

Decorate a controller with RefreshPreferences

Decorate a controller with an EPiServer.Find.Personalization.RefreshPreferences attribute to get attributes from the API when it executes any action method on the controller. To avoid unnecessary refreshing, check the IPreferenceRepository for attributes first, or use the controller to track if a refresh was already done for the visitor.

namespace OptimizelySite2.Controllers {
  public class MyController: PageController < MyPage > {
    public ActionResult Index(MyPage currentPage) {
      return View(currentPage);

The Recommendations API call is asynchronous, so it has little effect on the time it takes to execute the controller.

After retrieval, CMS stores the attributes in an EPiServer.Find.Personalization.IPreferenceRepository. The default implementation stores the attributes in the session and a cookie for fast retrieval during or between sessions no longer than two days apart.

If you want to override the default, implement EPiServer.Find.Personalization.IPreferenceRepository and change the implementation using the conventions during initialization: IClient.Personalization().Conventions.PreferenceRepository. The interface has two methods to implement, Save and Load, which are self-explanatory.

Execute personalized search queries

To enable personalization in Optimizely Search & Navigation queries, add .UsingPersonalization() to the query on the search client. CMS scores the results according to attribute data.


var result = _client.Search<ProductContent>()