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

Personalization.Commerce 2 breaking changes for Recommendations

Describes the changes from Personalization Commerce version 1 to version 2.

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.