Last updated: Feb 05 2018

Area: Episerver Commerce, Episerver Perform Applies to versions: EPiServer.Personalization.Commerce 1.0 and higher


The Episerver Commerce native integration package, EPiServer.Personalization.Commerce, integrates Commerce with the Episerver personalization features, and Episerver Perform. The package lets you track user behavior then use that information to show personalized product recommendations.

EPiServer.Personalization.Commerce contains the integration APIs for Commerce. You also need an Episerver Perform environment to receive tracking data and serve recommendations.

In this topic

Obtaining an Episerver Perform environment 

To order an Episerver Perform environment, contact your account manager to place an order for the service. When your environment is ready, you receive an email containing values needed to configure the native integration package.

Installing and configuring the native integration package

The native integration package is available via the Episerver NuGet feed. After installing it, you must modify the configuration to include settings for your Episerver Perform environment. Recommendations reads its configuration from the <appSettings> section. The following keys are used.

The export function has a few settings in addition to those above. These settings need to be set via code on the default CatalogFeedSettings instance:

var catalogFeedSettings = ServiceLocator.Current.GetInstance<CatalogFeedSettings>();
catalogFeedSettings.DescriptionPropertyName = "...";
Property Description
ExcludedAttributes   Names of product properties to exclude from the catalog feed.
DescriptionPropertyName   The product feed requires each item (product) to have a description. Set this to a property name you want to use as description. Default value is "Description".
AssetGroupName   The first asset in this group is used for the item's image link. The default value is "default".

Exporting your catalog to Episerver Perform

In order for Episerver Perform to provide accurate and valuable recommendations, your catalog must be exported to the Episerver Perform engine on a regular basis. You should schedule the export job to run every 24 hours.

To export a catalog, start your site, enter admin mode, and launch the Export Product Feed scheduled job. If the job finishes with a successful status, your catalog was successfully exported. 

The scheduled job has two parts:

  • Serialize the catalog to XML, compress it, and store it as a blob.
  • Notify Episerver Perform that a new catalog is available.

To notify Episerver Perform that a new catalog export is available, the scheduled job calls the Episerver Perform REST API (via HTTPS) and passes a callback address and an authorization token. When the Perform engine has the resources to handle downloading the catalog, it calls the specified callback method and passes the token. If the callback method determines that the passed token is valid, the download is allowed.

The callback address is formulated using SiteDefinition.SiteUrl as the host and a static path. It is recommended that the SiteUrl be set to use the HTTPS protocol.

Activating widgets

The following are key concepts within Episerver Perform: 

  • TrackingTypes, which describe visitor actions that can be tracked.
  • Widgets, which describe how recommendations are calculated for a specific TrackingType.

When a new environment is set up, it has the following widgets. Note that widgets are only configured for five of the eleven TrackingTypes. See TrackingTypes for the full list.

In a new environment, all widgets are inactive. Before you can track and receive recommendations, you must activate them. To do this, use the WidgetService within EPiServer.Personalization.Commerce.

Sample code is provided in the SiteInitialization.cs file within the Commerce sample site source code. 

Tracking and recommendations

Tracking user activities and retrieving recommendations are performed simultaneously in a single round trip to the Episerver Perform environment. This round trip is made synchronously and adds a small processing overhead to all tracked requests. The following diagram describes the flow for page requests that end up in a controller action decorated with a CommerceTrackingAttribute. The flow is identical for tracking requests not triggered by the CommerceTrackingAttribute except the custom tracking code replaces the OnActionExecuting step.

User identification

To provide good recommendations, Episerver Perform tracks a visitor's activities over time. This is accomplished by assigning visitors a consolidated user ID (CUID), which is stored in a cookie.

Tracking types

User activities that can be tracked are contained in the TrackingType enum. The following table lists them. Track as many activities as possible - more tracked activities result in better recommendations. The Attribute Support column indicates whether you can track the activity by decorating controller actions with an attribute - see CommerceTrackingAttribute.

SearchResults and Order tracking cannot be tracked via the CommerceTrackingAttribute because the required data is not available when the CommerceTrackingAttribute code is executed. Track these activities  without using the tracking attribute.

Note: While the following tracking types are supported by the native integration API, they should not be used with the default widget setup - they add overhead without improving recommendations.

TrackingType Activity Attribute Support
Attribute View products with a specific attribute value, for example Color: Red. No
Brand View products of a specific brand. No

Sending tracking information

Using the CommerceTrackingAttribute

The CommerceTrackingAttribute is an ActionFilterAttribute designed to be placed on controller actions. The parameter for the CommerceTrackingAttribute constructor is a TrackingType from the table above. If the passed TrackingType is supported by the CommerceTrackingAttribute, it automatically collects the necessary data and performs a tracking request in the OnActionExecuting method. In the following example, the Index method of the start page controller sends a home page tracking request when executed.

public ViewResult Index(StartPage currentPage)
{ ... }

Tracking without using the CommerceTrackingAttribute

If the TrackingType is not supported by the TrackingAttribute, or if the action to be tracked cannot be tied directly to a controller action, you need to handle tracking in a more hands-on way. In these cases, you must manually:

  1. Create the relevant TrackingData object.
  2. Pass the TrackingData object to the ITrackingService.Track extension method.

To construct TrackingData objects, call methods on TrackingDataFactory. This acts as a bridge between the Commerce system and the tracking system - accepting objects from the Commerce world as parameters and returning objects that are disconnected from Commerce. To send tracking data, call the ITrackingService Track extension method. In the following example, both TrackingDataFactory and ITrackingService are injected via constructor:

var trackingData = _trackingDataFactory.CreateCategoryTrackingData(category, httpContext);
var result = _trackingService.Track(trackingData, httpContext, currentContent);

The Track extension method also has a asynchronous version, TrackAsync, that can be awaited in asynchronous controller actions for improved performance.

Linking user actions with recommendations

Valuable business intelligence is based on knowing which recommended content a visitor acts upon. When the TrackingDataFactory creates ProductTrackingData, it uses an instance of IRecommendationContext to ask whether the current request was based on previous recommendations, by calling its GetCurrentRecommendationId method. If the value returned from the method is greater than zero, it is passed on as ClickInfo on the ProductTrackingData object.

The default implementation of this interface is NullRecommendationContext. It always returns zero. To allow ClickInfo to be sent as part of the ProductTrackingData, you must make a custom implementation of this interface and register it in your IoC container.

The Commerce reference site has a sample of such an implementation, storing the RecommendationId values using cookies, which are then read from the RecommendationContext when new ProductTrackingData is being instantiated.

Consuming recommendations

Depending on how the Episerver Perform environment is configured, different types of tracking events may or may not return recommendations. This section explains a general case where recommendations are returned and should be displayed to the visitor.

Using the CommerceTrackingAttribute

As the CommerceTrackingAttribute executes code in the OnActionExecuting method, the recommendations are available as soon as the controller action method is entered. To get recommendations, call the Controller extension method GetRecommendationGroups.

public ViewResult Index(StartPage currentPage)
    var recommendations = this.GetRecommendationGroups(); 
... }

The method returns a collection of Recommendation objects, where each object has an Area and a collection of ContentReferences referencing the recommended products. The Recommendation object can be used to create model data to display recommended products to a site visitor.

The number of Recommendation objects and the names of the areas are dependent on how the Episerver Perform environment is configured. The name for these recommendation groupings on the Episerver Perform side is widgets. A widget contains information about where recommendations should appear on a page (left, right, bottom, and so on.) and which algorithms are used to generate recommendations such as similar products, and cross sells.

var productRefs = widgetService.UpdateWidget().Where(x => x.Area == "someWidget").SelectMany(x => x.RecommendedItems); 

Without using the CommerceTrackingAttribute

Working with the recommendations returned from the ITrackingService.Track extension method is similar to working with the attribute. A GetRecommendationGroups extension method exists for the returned tracking response data and works the same way as with the controller.