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

Optimizely Personalization developer guides

Recommended reading 

Optimizely 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

Personalization 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 Personalization in the Optimizely User Guide 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 Content Recommendations how to install and implement content recommendations.  

Product, email, and search recommendations

Optimizely Product Recommendations use 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.

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. Optimimizely Visitor Intelligence lets you visualize and analyze profile data, and create segments for targeted campaigns.


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 method options

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

  • Native integrations are specific for the Optimizely product platform.
  • Server-to-Server and JavaScript integrations are general personalization system integration methods. 

Native integrations

Native integrations let Optimizely products access the core personalization 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 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

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.

Displaying 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 personalization 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 Personalization Portal, by using "hand-picked" strategies.

Implementing product recommendations

The Optimizely Personalization 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 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 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 Personalization 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.

Promote. If provided, Optimizely 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, 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.


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

Cookie usage in Product Recommendations

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 integration, it is the client site responsibility to manage cookies, and the implementation is indifferent to Product Recommendations.

Standard and JSON integration cookies

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 Optimizely 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, Product Recommendations does not track current visitor behavior.
peerius_ct Used 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.
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.

Native integration cookies

Cookie Name Purpose
epi_RecommendationsTrackingSessionId 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.
epi_RecommendationsTrackingUserId 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 Optimizely Support to change the expiration time.

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

Related topics

Blog posts

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

Last updated: Apr 09, 2020

Recommended reading