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

Advance API

Recommended reading 

Note: This is legacy content because Episerver Advance was replaced by Episerver Content Recommendations. If you are using Episerver Advance, you should upgrade your solution. See also Discontinued services and products.

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.

Installation and configuration

Install the integration package that tracks changes to entities in CMS such as content, categories, sites, content types and synchronizes them with the service. A scheduled job exists for the first time provisioning of content from the site to the service, changes made to content after this point are tracked automatically.

  1. Install NuGet package EPiServer.CMS.CloudSynchronization.
  2. Add the following settings to web.config, access keys comes with the product (Advance):
       <add key="episerver:CmsCloudSynchronizationKey" value="X" />
       <add key="episerver:CmsCloudSynchronizationSecret" value="Y" />
       <add key="episerver:CmsCloudSynchronizationUri" value="https://Z.epcc.episerver.net" />
  3. Go to admin view and start job Cloud Provisioning manually.

    Note: Do not schedule this job, it should only run once.

  4. Verify that it completed successfully in the job history.

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

  5. In web.config, set the values in the following appSettings keys:
    <add key="episerver:RecommendationServiceKey" value="ChangeThis" />
    <add key="episerver:RecommendationServiceSecret" value="ChangeThis" />
    <add key="episerver:RecommendationServiceUri" value="" />
  6. Install the EPiServer.Personalization.CMS NuGet package from the Episerver NuGet source to your site. The EPiServer.Personalization.CMS package connects to Recommendation Service to retrieve recommendations for content.
  7. 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 find this information helpful? Please log in to provide feedback.

Last updated: Aug 05, 2020

Recommended reading