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


Describes getting started with Recommendations and some of the common features.

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

The Recommendations suite includes the following features.

Get started

Recommendations 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 onboarding, Optimizely sends the required scripts, configuration keys, and credentials to the technical contact for your project. Use the keys to configure tracking for your websites. Contact Optimizely for questions about the onboarding process.

See also Recommendations for information about how to work with these features.

Content recommendations

Optimizely Content Recommendations use 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 Optimizely Content Recommendations for how to install and implement content recommendations.

Product, email, and search recommendations

Optimizely Product Recommendations uses a tracking component, a core recommendations system, and general or product-specific integrations. The Recommendations system has a recommendation service that is fed with visitor tracking data from Optimizely Customized Commerce for product recommendations, and Optimizely Search & Navigation (legacy) for personalized search results. The recommendations engine processes visitor data and predicts intent.

Optimizely Email Product Recommendations can trigger personalized emails based on visitors' website actions. You can store tracking data in Optimizely Profile Store (Customer Data Platform), or any other source. Optimizely Visitor Intelligence lets you visualize and analyze profile data, and create segments for targeted campaigns.

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

Integration method options

Integration method options let you connect with the tracking service. See Integration guides.

Native integrations

Native integrations let Optimizely products access the core Server-to-Server API for managing JSON tracking data and JSON-formatted content. Use native integrations for the Optimizely 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 Optimizely Recommendations 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

The JavaScript integration method uses JSON-based page tracking and product recommendations to provide flexible control for tracking visitor interaction, and designing the recommendation appearance. See JavaScript API.

Display recommendations in widgets

A widget is a block that displays recommendations, either on a web page or in an email message. A widget provides 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 Recommendations implementation, Optimizely works with you to define KPIs and recommendation strategies, and customize algorithms based on those strategies. Optimizely sets up widgets for the home and product pages, and recommendations are automatically served based on these default configurations. You can override this default "product strategy" manually from the Recommendations Portal, by using "hand-picked" strategies.

Implement product recommendations

The Optimizely Recommendations suite is based on a service, and a set of NuGet packages that provide 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 Recommendations Portal.
  • Deploy, test and adjust the setup.

Key integration components

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

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, send Optimizely an up-to-date mapping between email addresses and pseudonymized user IDs. This needs to be provided only once so that Optimizely Recommendations can replace existing customer email addresses with their corresponding pseudonymized user ID.

Mail. Continually provide your ESP (Email Service Provider) with 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 Optimizely Campaign. Alternatively, you need to advise your ESP to provide an API extension that lets Optimizely 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.

(Legacy) Promote. If provided, Optimizely Recommendations 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, are not stored, so cannot be used for analytics and reporting.

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

Product reference

The product reference (productId) serves as an important connector between your data and the Optimizely recommendations engine; changes to this identifier breaks a connection between collected behavior and your product catalog. To prevent this connection from breaking, inform Optimizely 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 Optimizely.

Install recommendations

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

Cookie usage in Product Recommendations

Optimizely Product Recommendations uses the following cookies in standalone implementations. For the native integrations, cookies are implemented in the native integration components for Optimizely Commerce.

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

Standard and JSON integration cookies

Cookie NamePurpose
peerius_userRequired. 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 Optimizely Support to change the expiration time.
peerius_sessRequired. 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_ridTracks recommendations clicked by visitors. Managed by Product Recommendations.
peerius_stat_optoutIf set by the client, Product Recommendations does not track current visitor behavior.
peerius_ctUsed internally by Product Recommendations to detect if the visitor disables cookies, or if the 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.
viewedPeeriusPopUpModalOptional mechanism to track Promote (legacy) impressions in pop-ups.
do_not_trackMechanism 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.

Native integration cookies

Cookie NamePurpose
epi_RecommendationsTrackingSessionIdRequired. Contains the visitor's tracking session ID. Valid for four hours since last visitor activity. Generated by Product Recommendations if not present or expired.
epi_RecommendationsTrackingUserIdRequired. 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 Optimizely Support to change the expiration time.

Related blog posts