Last updated: Jun 05 2018

Area: Episerver CMS, Episerver Advance Applies to versions: Not applicable

Advance API

This topic describes how to install and configure the native integration for content recommendations for Episerver Advance, the Episerver CMS-specific part of the Episerver personalization suite. 

Content recommendation tracking

Tracking is used for different purposes, for example to provide personalized content recommendations, such as articles on a news site. 

Episerver Advance includes the native integration between Episerver CMS and the core personalization system, and is based on a content service for retrieving content recommendations, and client packages, for configuring the tracking for your website. See the Personalization section how to get started with Advance.

Page view tracking

The tracking functionality in Episerver CMS is based on page views by website visitors. The tracking component tracks page views, and sends data in a predefined format to a profile tracking instance. That data is the source for the recommendation service.   

See Page view tracking for more details about tracking types and attributes for content, and how to install the core tracking.


The EPiServer.Personalization.CMS package connects to Recommendation Service to retrieve recommendations for content.

Installation and configuration

When you place and order for and register Recommendation Service, Episerver provides a HMAC key pair and a service URL.

  1. In web.config, set the values in the following appSettings keys:
    <add key="episerver:RecommendationServiceKey" value="application key" />
    <add key="episerver:RecommendationServiceSecret" value="secret key" />
    <add key="episerver:RecommendationServiceUri" value="" />
  2. Install the EPiServer.Persionalization.CMS NuGet package from the Episerver NuGet source to your site.
  3. Retrieve recommendations for content:
    1. Create a recommendation request with following parameters
      • siteId. The ID of the site that has the content that needs to receive recommendations.
      • contentId. The ContentGuid of the content.
      • languageId. The language of the content.
      • numberOfRecommendations. The number of recommendations that you want to have for the content.
    2. Retrieve recommendations using the instance of IRecommendationService.
    3. The recommendation result is a list of RecommendationResult objects.

    For example:

    public async Task<ActionResult> Index(SamplePage currentPage)
          var siteId = SiteDefinition.Current.Id.ToString();
          var contentId = currentPage.ContentGuid.ToString();
          var languageId = currentPage.Language.Name;
          var rRequest = new RecommendationRequest
              siteId = siteId,
              context = new Context { contentId = contentId, languageId = languageId },
              numberOfRecommendations = 5 //or another number as needed
          var recommendationService = ServiceLocator.Current.GetInstance<IRecommendationService>();
          var result = await recommendationService.Get(this.HttpContext, rRequest);

Sample code

Use the available sample code package to explore Episerver Advance. The sample code contains a CMS block that can be added to a page for displaying recommended content. The sample code block is available for download on Episerver GitHub.

Related topics

Do you have feedback on this documentation? Send an email to documentation@episerver.com. For development-related questions and discussions, refer to our Forums on https://world.episerver.com/forum/