Track and recommend

Tracking provides personalized recommendations by following the user journey and storing session and user behaviors. This enriches the machine learning (ML) algorithms used to track key performance indicators (KPIs). With Optimizely Commerce Connect-native integration, a JSON payload is sent to an API endpoint on the Optimizely Product Recommendations servers. The payload contains information about the page, such as page type, URL, and product codes.

Optimizely recommends tracking all points of the user journey to ensure wide coverage of behavior used by ML algorithms. If you cannot do this, track product, basket, and order pages — and any other pages that should show recommendations — at a minimum.

Product Recommendations relies on user tracking to maintain a cross-platform experience. Track the user email or pseudonymized ID at key points in the user journey, such as logging in, the checkout process, or any other point where the user ID is captured according to business requirements.

Tracking data includes the user's IP address by default. The recommendations service does not store the IP address — it uses the address only for in-session geolocation, which improves recommendation accuracy.

To exclude the IP address from tracking data, set episerver:personalization.SkipUserHostTracking. See Install and configure the native integration packageInstall and configure the native integration package.

Alternatively, register a custom implementation of the IRequestTrackingDataService interface (namespace EPiServer.Tracking.Commerce) to include or exclude the IP address. The default implementation uses SkipUserHostTracking, but a custom implementation can vary behavior based on user preference, cookies, or other context.

Tracking data includes the user's email address by default. To exclude the email address, set episerver:personalization.UsePseudonymousUserId. See Install and configure the native integration packageInstall and configure the native integration package.

Alternatively, register a custom implementation of the IUserIdentityService interface (namespace EPiServer.Personalization.Common) to include or exclude the email address. If you plan to switch from email to a pseudonymous user identifier (by configuration or customization), coordinate with the Recommendations service team for any site that has existing tracking data. Otherwise, existing tracking data and the profiles built from it are lost when the user identifier changes. See Migrate Server-to-Server API version 1.3 to 1.4Migrate Server-to-Server API version 1.3 to 1.4.

Tracking is used for different purposes, for example, to provide personalized product recommendations on an ecommerce site. Tracking visitor activities and retrieving recommendations occur simultaneously in a single round trip to the Optimizely Product Recommendations environment. The round trip is synchronous and adds a small processing overhead to all tracked requests.

The following diagram describes the flow for page requests that reach a controller action decorated with a CommerceTrackingAttribute. The flow is identical for tracking requests not triggered by the CommerceTrackingAttribute, except that custom tracking code replaces the OnActionExecuting step.

To provide good recommendations, Product Recommendations tracks a visitor's activities over time 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.

In this article, tracking is sent to the Optimizely Product Recommendations service, but any source can consume tracking of Optimizely Commerce Connect 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 configuring the service's recommendation widgets 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 or airline, where available products depend on flight type.

The following issues may occur when you implement tracking. See also Recommendations in Commerce Connect for information about solving issues with tracking integration. If there are additional requirements for tracking or a problem persists, contact your customer success manager or SupportSupport.

If a page loads on your site and does not trigger a tracking request, tracking may not be implemented for that page type. If you have implemented tracking, check other pages of the same type to see if they are also tracking. If not, check other page types, and if that fails, refresh the Session Viewer page.

A single page view on your site should be associated with a single tracking request in Session Viewer. Multiple tracking requests can lead to unnecessary processing in the Recommendations service and may also cause conflicts when rendering recommendations. Ensure that any calls to internal or external APIs (such as calls to construct widget HTML) do not trigger methods that create tracking.

The refCode passed in the tracking request is not associated with any product in any previous feeds exported for this environment. The refCode must match the root product in the Commerce Connect catalog and the GUID tag in the feed export. The following images show an order placed with placeholder products.

The category passed in the JSON payload does not match any categories passed in past feed exports. Cross-check the category passed in the JSON payload with the tracking information of a product that should be included within this category. Either the category passed in tracking is incorrect, or the categories provided in the feed export are incorrect. Placeholder categories do not exist within Recommendations, so tracking defaults to the other page type to prevent the request from failing.

Optimizely defines the following page types as predefined tracking types: Home, Search, Category, Product, Basket, Checkout, Order, Wishlist, Brand, and Attribute. If you need recommendations on a page type outside this set, contact Optimizely to receive further setup instructions.

Optimizely supports additional, real-time filtering based on custom information provided on a per-page level so that you can accommodate business rules, such as showing a product only if the user has permission to view or buy that product. Coordinate custom requirements with your Optimizely contact.

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

Because the CommerceTrackingAttribute executes code in the OnActionExecuting method, the recommendations are available when the controller action method is entered. To get recommendations, call the controller extension method GetRecommendationGroups.

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

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

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 it does with the controller.

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

JavaScript tracking APIs support setting RecommendationId for ProductTrackingData, which is read from the TrackingProxy and sent to the Product Recommendations engine. If you use JavaScript API tracking, you do not need to use cookies or RecommendationContext. Commerce Connect reference sites have changed the way they store RecommendationId values. Now you use a query string by adding a RecommendationId parameter in the data-url attribute of the Shared/_RecommendationsTemplates.cshtml template.

Commerce Connect reference sites no longer use RecommendationContext. See also Client-side API integrationClient-side API integration.

When a user selects a recommended product, the Commerce Connect reference site redirects to the Product Detail page with the RecommendationId value passed in as a query string. The JavaScript TrackingDataFactory.createProductTrackingData API then gets the RecommendationId value from the query string and creates tracking data to send to the Tracking Proxy.

The following image describes this process.

Render recommendations on the site and track them correctly so the system can attribute user interactions and generate accurate reports. Click-tracking is the basis for key metrics that measure recommendation performance, such as click-through rate and click-to-purchase. If click-tracking is incorrectly implemented, reports in the Recommendations Portal show no Optimizely-generated revenue.

To verify that click-tracking is implemented correctly:

The following image shows the response. The click is logged as "info":{"smartRecs":[{"click":"ok","id":60088462}]}.

The following issues may occur when you implement Recommendations.

This can be caused by an inconsistent product refCode between the product page and order page, or by incorrectly implemented click-tracking. If the issue persists, contact Optimizely for assistance.

There are several reasons this may happen, but you can analyze the JSON response to help find a root cause. The response payload is at Console > Response > JSON.

When the response JSON contains the smartRecs object with an empty array [] as the value, recommendations are disabled in the request using the "smartProducts" : [] flag. If recommendations should be returned in this instance — for native integrations, check that CommerceTrackingData.SkipRecommendations() is not being called before passing it to the TrackingService; for JavaScript integrations, consult with Optimizely for more details.

When the response JSON does not contain the smartRecs object, there are no widgets enabled for that page type within Recommendations. If a widget should be returned for the page type being checked, consult with your Optimizely contact for more details.

The following response shows the smartRecs array has a single widget for this page type. However, the recs object is returning an empty array. To debug this:

If these steps do not solve the issue, contact Optimizely for further support.

For native integrations, in cases where you have custom widgets set up outside the default set of six widgets enabled on home, category, search, product, and basket pages, re-activating widgets within your instance resets the Recommendations configuration to the default set of widgets enabled per page. See Activate widgetsActivate widgets.

Activate widgets once per environment. If custom widgets are not returned, contact Optimizely for support.

For JavaScript API integrations, check that tracking is in place where you expect recommendations and verify that recommendations are being returned through the PeeriusCallbacks.smartRecs callback function. If recommendations are returned, the issue may lie in the client-side rendering — contact Optimizely for support.

To use output caching for pages that show recommendations, you must use the client-side API integrationclient-side API integration 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 the use of the ContentOutputCache attribute. 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 see the cached recommendations, and user behavior is not tracked.