HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Install Content Recommendations

Describes the NuGet packages and initial configuration to set up Optimizely Content Recommendations integration for Optimizely Content Management System (CMS).

What is included in the integration NuGet package

  • A UI module that integrates the Optimizely Content Recommendations dashboards and configuration in the Optimizely Platform navigation.
  • Automatically adds visitor behavior tracking to pages, to build user behavior profiles that can give relevant content recommendations.
  • A Content Recommendations block that editors can add to pages where they want content recommendations to appear.


  • A subscription to the Content Recommendations service and the appropriate configuration information for the environment (see Configuration section below), and user login credentials for the Content Recommendations UI.
  • An Optimizely Content Management System (CMS) website implementation that uses RenderRequiredClientResources in the HTML head element. (This is where the tracking script will be injected.)
  • The website implementation has been set up for Collecting metadata.
  • The website is open to the public internet so the Content Recommendations service can reach it and index the site content.



Before installing Content Recommendations, make sure you have widget deliveries set up. Otherwise, you will not see any widget deliveries in the drop-down widget selector.


Install the EPiServer.Personalization.Content.UI package in your Optimizely solution. If you have already set up your NuGet feed, skip to Step 6.

  1. In Visual Studio, select Tools > NuGet Package Manager > Package Manager Settings.
  2. Select Package Manager > Package Sources.
  3. Click Add (+) to add a new package source.
  4. Add Name as Episerver, and the package Source as
  1. Click OK.



    NuGet package manager has to be version 2.8.50126.477 or higher to install Optimizely packages.

  2. Open the solution file in Visual Studio and make sure the solution file is saved (required to make the NuGet tools available).
  3. In the Solution Explorer, right-click on References for the project, and select Manage NuGet Packages.
  1. Select Updates for the Optimizely package source, to locate available updates for your solution, and click Update for the desired packages.
  1. When the installation/update is completed, rebuild the solution.

Add the required configuration keys (see the Configuration section).


The following appsettings.json for CMS 12 and web.config for CMS 11 appSetting keys are used to set up the integration. For example:

"EPiServer" : {
  "ContentPersonalization" : {
     "Environment" : "instance.episerver.net",
     "ClientId"    : "1234567891015",
     "ClientName"  : "clientName",
     "ApiToken"    : "token"
<!-- Optimizely Content Recommendations -->
<add key="episerver:personalization.content.Environment" value="xxxxxx.xxxxxxxxxx.net" />
<add key="episerver:personalization.content.ClientId" value="xxxxxxxxxxxxxxxxxxxxxxxx" />
<add key="episerver:personalization.content.ApiToken" value="xxxxxxxxxxxxxxxxxxxx" />
<add key="episerver:personalization.content.ClientName" value="" />
Environment - episerver:personalization.content.EnvironmentThe environment for the account. For production environments this is idio.co but could be staging.idio.co for the environment, and so on.
ClientName - episerver:personalization.content.ClientName  [New in 0.3.0]
The friendly name of the client account in the service that is used to access the UI, such as _mywebsite_in https://manager.idio.co/mywebsite
ClientId - episerver:personalization.content.ClientIdThe alphanumeric client identifier of the account in the service that is sent with the tracking script.
ApiToken - episerver:personalization.content.ApiToken  The token used to authenticate to the API endpoint that provides available recommendation widgets to the property on the Content Recommendations block.
episerver:personalization.content.DisableDefaultTrackingOptional. If set to true, the default tracking script is not rendered in the HTML head section. Use this if you want to customize the tracking script or already have the tracking script included and do not want to remove it.

Add recommendation block to a page



At least one widget delivery needs to be set up in the Engage/Deliveries view of the Content Recommendations UI, see Setting up deliveries.

  1. In CMS edit view, create and place a new instance of the Content Recommendations block on a page.
  2. Use the All Propertiesview for the block to set:
    • The number of recommendations to show.
    • Which widget delivery to pull recommendations from.
    • An HTML fragment using templates for content properties to render the recommendation. 



      Omit the script element surrounding the template because it is automatically included by the integration.

  1. Publish the block and the page.