Personalization.Commerce 2 breaking changes for Recommendations

In version 2.0, Optimizely introduces the concept of scope, which lets a single Commerce installation connect to more than one PerformEngine instance. See also: Using Scopes in a Multisite Installation.

In this release, we also remove the fallback support for older _appSetting _key names. Although this release contains breaking changes, we have strived to minimize the impact for implementations that will not use the scope feature.

Upgrading to version 2.0 requires code or configuration changes only if your environment has any of the following conditions:

your code directly accesses our configuration classes
you created custom implementations for any public interface
you have configuration settings with beta version names

PersonalizationClientConfiguration changes

The following properties have been removed from PersonalizationClientConfiguration:

AdminToken
BaseApiUrl
ClientToken
Site

To access these settings in version 2.0, you must call the GetConfiguration(string scope) method. This method returns a ScopeConfiguration instance that contains the properties above. If you do not use the scope feature, you should pass null to the method.

Public interface changes

To support the new scope feature, the scope value needs to be passed around inside the API, so it can be evaluated by any custom implementation of our interfaces. The default implementation of our interfaces ignores the scope value and behaves the same regardless of its value.

If you do not intend to use the scope feature, you only need to update your methods’ signatures – you do not have to modify your code to evaluate the parameter value.

The following interfaces have methods where a “string scope” parameter has been added to the signature:

EPiServer.Personalization.Commerce.CatalogFeed namespace

ICatalogFeedService
ICatalogItemFilter
IEntryAttributeService
IEntryInventoryService
IEntryPriceService
IEntryUrlService

EPiServer.Personalization.Commerce.Tracking namespace

ITrackingDataHandler

Configuration changes

Support was removed for the beta names of the configuration settings. So, the following keys are no longer valid:

episerver:perform.BaseApiUrl
episerver:perform.Site
episerver:perform.ClientToken
episerver:perform.AdminToken
episerver:perform.RequestTimeout
episerver:RecommendationsBaseApiUrl
episerver:RecommendationsSite
episerver:RecommendationsClientToken
episerver:RecommendationsAdminToken

Use these keys instead:

episerver:personalization.BaseApiUrl
episerver:personalization.Site
episerver:personalization.ClientToken
episerver:personalization.AdminToken
episerver:personalization.RequestTimeout

Catalog feed data changes

The field containing the categories for each exported product exported in the catalog feed no longer include the catalog name in the category outline. That is, what was previously exported as "CatalogName > CategoryName > SubCategoryName" is now exported as "CategoryName > SubCategoryName".

This could affect filters, triggers, etc. set up in the Personalization portal if they use categories from the catalog feed.

The category tracking data, when obtained from TrackingDataFactory.CreateCategoryTrackingData, was changed to match the change in the catalog feed.