Area: Episerver Product Recommendations, Episerver Personalized Search & Navigation, Episerver Content Recommendations
Applies to versions: Not applicable

Episerver Personalization developer guides

Recommendations [hide]

Episerver Personalization is a suite of cloud-based products, combining machine learning, artificial intelligence, and statistical analysis.

The Personalization suite includes the following features.

Getting started

The personalization functionality is based on a back-end service, tracking and user interface components added to the website, and configuration keys for service access. As part of the onboarding, Episerver sends the required scripts, configuration keys, and credentials to the technical contact for your project. Use the keys to configure the tracking for your websites. Contact Episerver for questions regarding the onboarding process.

Content recommendations

Episerver Content Recommendations uses a recommendation service and tracking scripts for content processing and interest profiling. Content recommendations are defined through sections and delivered in widgets added to the page templates. See Content Recommendations how to install and implement content recommendations.  

Product, email, and search recommendations

Episerver Product Recommendations are based on a tracking component, a core personalization system, and general or product-specific integrations. The personalization system has a recommendation service that is fed with visitor tracking data from Commerce for product recommendations, and Search & Navigation for personalized search results. The personalization engine processes visitor data and predicts intent.

With Episerver Email Product Recommendations, you can trigger personalized emails based on visitors' website actions. Tracking data can be stored in Episerver Profile Store (Customer Data Platform), or any other source. Episerver Visitor Intelligence is used for visualizing and analyzing profile data, and to create segments for targeted campaigns. See Personalization in the Episerver User Guide how to work with these features.


To get the personalization running for a site, configure access to the tracking API, so you can post usage data and get recommendations back. 

Integration options

There are different integration methods to connect with the tracking service. Native integrations are specific for the Episerver product platform. Server-to-Server and JavaScript integrations are general personalization system integration methods. See Integration guides.

Native integrations

Native integrations provide Episerver product-specific access to the core personalization Server-to-Server API for managing JSON tracking data and JSON-formatted content. It is recommended to use native integrations for the Episerver platform, to simplify implementation of basic tracking and the product catalog feed. See Native integrations.

Server-to-server integration

The Server-to-Server API lets you integrate any website or application with products in the Episerver Personalization suite. In response to the tracking data sent, recommendations are returned with the Server-to-Server API response payload, based on JSON tracking data and JSON-formatted content. See Server-to-Server API

JavaScript integration

This integration method uses JSON-based page tracking and product recommendations. These components provide flexibility in controlling tracking of visitor interaction, and design of recommendation display. See JavaScript API.

Widgets and recommendations

A widget is a block displaying recommendations, either on a web page or in an email message. Widgets provide an automated way to add recommendations based on visitor interaction and other visitors' purchasing behavior. The recommendations are configured in the strategy defined for each widget, and are calculated by specific algorithms based on visitor tracking data.

During onboarding and personalization implementation, Episerver works with the customer to define KPIs and recommendation strategies, and customize algorithms based on this. Widgets are set up for example for the "home" and "product" pages, and recommendations will be automatically served based on these default configurations. This default "product strategy" can be manually overridden from the Personalization Portal, by "handpicked" strategies.

Implementing product recommendations

The Episerver Personalization suite is based on a service, and a set of NuGet packages providing access to the APIs. 

The service onboarding and solution setup typically involves these steps:

  • Analyze requirements, define recommendation strategy and integration method.
  • Install and configure service and components, set up test environment.
  • Export product catalog feed, review and adjust.
  • Implement tracking, create content types, templates, and widgets. 
  • Work with conversion data and merchandising rules in the Personalization Portal.
  • Deploy, test and adjust the setup.

Key integration components

Personalization has key components that you should not alter. If you need to alter the following components, co-ordinate with Episerver.

User tracking

Changes to user tracking needs can result in loss of behavior and core functionality, such as if you switched from tracking plain email addresses to pseudonymized user IDs or vice versa.

Recommendations. To prevent user behavior from being lost, you need to send Episerver an up-to-date mapping between email addresses and pseudonymized user IDs. This only needs to be provided once so that Episerver Personalization can replace existing customer email addresses with their corresponding pseudonymized user ID.

Mail. You need to continually provide your ESP (Email Service Provider) an up-to-date mapping between email addresses and pseudonymized user IDs. Your ESP needs to create a new placeholder (mail merge variable) that represents the pseudonymized user ID. You then replace the email address placeholder from all your Mail campaigns with this new placeholder.

Triggers. Your ESP must handle pseudonymized user IDs. Currently, in Triggers, this functionality is provided only by Episerver Campaign. Alternatively, you need to advise your ESP to provide an API extension that lets Episerver call methods that accept the pseudonymized user ID instead of email address. Also, provide and maintain a mapping between pseudonymized user ID and customer email address that your ESP can use to lookup, to send the email to the appropriate customer based on their pseudonymized user ID.

Promote. If provided, Episerver Personalization can use the visitor's IP address, within their session, to do a geolocation lookup to identify the approximate location of the visitor for a personalized online experience. IP addresses if provided will no longer be stored, so cannot be used for analytics and reporting.

When you provide and test a user mapping, co-ordinate with Episerver to schedule a deployment and receive further instructions.

Product reference

The product reference (productId) serves as an important connector between your data and the Episerver recommendations engine; changes to this identifier breaks a connection between collected behavior and your product catalog. To prevent this connection from breaking, inform Episerver of any plans to change the format of product references in your feed and tracking implementation. Provide a mapping from the old to the new product references and co-ordinate a deployment with Episerver.


See Install and configure personalization how to install and configure the NuGet packages needed to access the API, and start working with personalization. 

Cookie usage

The following cookies are used by Product Recommendations in standalone implementations. For the native integrations, cookies are implemented in the native integration components for Episerver Commerce.

Standalone Product Recommendations use cookies to keep track of visitors and their sessions. In standard and JSON integration, cookies are managed by Product Recommendations  /tracker/tracker.page HTTP request. In server-to-server integration, it is the client site responsibility to manage cookies, and the implementation is indifferent to Product Recommendations.

Cookies in the following table are only used in standard and JSON integrations.

Cookie Name Purpose
peerius_user Required. Contains the customer user ID (CUID) of the visitor in Product Recommendations. Generated by Product Recommendations if not present. Valid indefinitely by default, but you can contact Episerver Support to change the expiration time.
peerius_sess Required. Contains the visitor's tracking session ID. Valid for four hours since last visitor activity. Generated by Product Recommendations if not present or expired.
peerius_rid Tracks recommendations clicked by visitors. Managed by Product Recommendations.
peerius_stat_optout If set by the client, current visitor behavior is not tracked by Product Recommendations.
peerius_ct Used internally by Product Recommendations to detect if cookies are disabled by the visitor, or browser does not support cookies. Valid for two seconds.
peerius_pass_{paramName} Optional mechanism to pass parameters between Product Recommendations requests. Rarely used. Valid for one hour or until next Product Recommendations request.
viewedPeeriusPopUpModal Optional mechanism to track Promote impressions in pop-ups.
do_not_track Mechanism to disable tracking for visitors that do not give tracking consent. Activated by client's site by providing any HTML element with ID equal to episerverDoNotTrackOption.

See Cookies for information about other cookies in the Episerver platform.

Related topics

Blog posts

Do you find this information helpful? Please log in to provide feedback.

Last updated: Apr 09, 2020

Recommendations [hide]