Area: Episerver Commerce, Episerver Product Recommendations
Applies to versions: EPiServer.Personalization.Commerce 2.1.0 and higher
Other versions:

Tracking and recommendations

Recommendations [hide]

This topic explains how tracking and recommendations work in Episerver Product Recommendations (formerly Perform), the Episerver Commerce-specific part of the Episerver personalization suite.

User identification

Controlling tracking of user IP address 

By default, tracking data sent to the Personalization service includes the user’s IP address. The IP address is not stored in the personalization service—it is only used in the session for geolocation purposes, to improve recommendation accuracy.

You can exclude the IP address from tracking data by using episerver:personalization.SkipUserHostTracking. See Installing and configuring the native integration package.

Alternatively, you can include/exclude IP address by registering a custom implementation of the IRequestTrackingDataServiceinterface (namespace EPiServer.Tracking.Commerce). The default implementation of this interface uses the setting mentioned above, but a custom implementation could vary the setting based on user preference, cookies, and so on.

Controlling tracking of user’s email address

By default, tracking data sent to the Personalization service includes the user’s email address. You can exclude email address from tracking data by using episerver:personalization.UsePseudonymousUserId. See Installing and configuring the native integration package

Alternatively, you can include/exclude user email address by registering a custom implementation of the IUserIdentityServiceinterface (namespace EPiServer.Personalization.Common).  If you plan to switch from email to a pseudonymous user identifier (by config or customization), you must synchronize with the personalization service team for any site with existing tracking data. Otherwise, existing tracking data and the profiles built from it are lost when the user identifier changes. See Migrating Server-to-Server API version 1.3 to 1.4.

Product recommendation tracking

Tracking is used for different purposes, for example to provide personalized product recommendations on an e-commerce site. Tracking visitor activities and retrieving recommendations are performed simultaneously in a single round trip to the Episerver Product Recommendations 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.

To provide good recommendations, Episerver Product Recommendations tracks a visitor's activities over time. Product Recommendations accomplishes this by assigning visitors a consolidated user ID (CUID), which is stored in a cookie. User activities that can be tracked are contained in the TrackingType enum. Track as many activities as possible - more tracked activities result in better recommendations.

Tracking here is sent to the Episerver product recommendation service, but tracking of Episerver Commerce data can be consumed by any source.

See Product tracking for details about tracking types and attributes for products, and how to install the core tracking.

Customizing tracking data

You can include custom tracking data in a tracking request by using the SetCustomAttribute extension method for CommerceTrackingData. Supported data types are limited to common numeric types, string, and DateTime.

A use case for custom tracking attributes is to configure recommendation widgets in the personalization service to filter recommendations based on a known customer preference or other data. For example, a website for browsing or preordering duty free goods for an airport/airline, where available products depend on flight type.

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

Linking visitor actions with recommendations

Valuable business intelligence is based on knowing which recommended content a visitor acts upon.

As of version 2.1.0, TrackingMode is obsolete. Also, Js tracking APIs and server tracking APIs are independent and work in parallel.

Js tracking APIs support setting RecommendationId for ProductTrackingData, which is read from the TrackingProxy and sent to the Product Recommendations Engine. So, if you use JS API tracking, you do not need to use cookies or RecommendationContext. Further, Commerce reference sites have changed the way they store RecommendationId values. Now, they use a Query String by adding a new RecommendationId parameter in the data-url attribute of the Shares\_RecommendationsTemplates.cshtm template.

And, Commerce reference sites no longer use RecommendationContext. See also: Recommendations client side API integration.

<button type="button"
        class="btn btn-block btn-sm quickview-button">

When a user clicks Recommendation products, the Commerce reference site redirects to the Product Detail page with the RecommendationId value passed in as a QueryString. Then, the JS  TrackingDataFactory.createProductTrackingData API gets the RecommendationId value from QueryString and creates tracking data to send to the Tracking Proxy.

  $(document).ready(function ()
      var refCode = '@Model.Product.Code';
      var productName = '@Model.Product.Name';
      var productTrackingData = TrackingDataFactory.createProductTrackingData(refCode, productName);
      productTrackingData["SkipRecommendations"] = true;
      var recommendationId =  parseInt(isNaN('@Request.QueryString["recommendationId"]')? '0': '@Request.QueryString["recommendationId"]');
      if (recommendationId > 0) 
          productTrackingData["recommendationId"] = recommendationId;
      productTrackingData["customAttributes"] = { 'marketId': Market.getSelectedMarketId() };

The image below describes this process.

tracking API.png

Consuming recommendations

Depending on how the Episerver Product Recommendations 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 depend on how the Episerver Product Recommendations environment is configured. The name for these recommendation groupings on the Episerver Product Recommendations 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.

Output caching

If you want to use output caching for pages that show recommendations, you must use the client side tracking API in version 2.1.0 (or later) of the EPiServer.Personalization.Commerce package.

Caching of content is controlled by the "httpCache"-prefixed settings of the applicationSettings element and usage of the ContentOutputCache attribute. Note that caching enabled by these settings does not apply to authenticated users. Output caching breaks the server-side tracking, because the request most often does not reach the page's controller - users will see the cached recommendations, and user behavior will not be tracked.

Related topics

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

Last updated: Jan 09, 2019

Recommendations [hide]