Intelligent Selling Services for SAP Commerce Cloud Integration

Note: Spartacus 2.x is no longer maintained. Please upgrade to the latest version.

Note: This feature is introduced with version 1.5 of the Spartacus libraries.

Overview

The SAP Commerce Cloud, Intelligent Selling Services for SAP Commerce Cloud solution provides real-time customer experience personalization for SAP Commerce Cloud. You can integrate Intelligent Selling Services for SAP Commerce Cloud with your Spartacus Storefront, including the Profile Tag and the Merchandising Carousel features.

For more information, see Intelligent Selling Services for SAP Commerce Cloud on the SAP Help Portal.

Requirements

To integrate Intelligent Selling Services for SAP Commerce Cloud with Spartacus, release 1905.9 of Commerce Cloud is required.

Also, the Anonymous Consent feature in Spartacus needs to be enabled. For more information, see Anonymous Consent.

Enabling Intelligent Selling Services for SAP Commerce Cloud in Spartacus

To enable Intelligent Selling Services for SAP Commerce Cloud in Spartacus, you need to configure both the Commerce Cloud back end, and the Spartacus front end.

Configuring the Back End for Intelligent Selling Services for SAP Commerce Cloud

The following steps describe how to add custom headers to your CORS settings, as well as how to define a consent template that allows events to be sent.

Add the x-profile-tag-debug and x-consent-reference custom headers to corsfilter.commercewebservices.allowedHeaders.

If you are using the Assisted Service Module, add these custom headers to corsfilter.assistedservicewebservices.allowedHeaders as well.

Note: The corsfilter.commercewebservices.allowedHeaders setting is for SAP Commerce Cloud version 2005 or newer. For SAP Commerce Cloud version 1905 or older, use corsfilter.ycommercewebservices.allowedHeaders instead.

For more information, see Configuring CORS.

Define a consent template with an ID of PROFILE, which will allow events to be sent.

You can define the consent template by importing the following ImpEx:

 $lang=en
 INSERT_UPDATE ConsentTemplate;id[unique=true];name[lang=$lang];description[lang=$lang];version[unique=true];baseSite(uid)[unique=true,    default=electronics-spa];exposed
 ;PROFILE;"Allow tracking for Intelligent Selling Services";"We would like to store your browsing behavior so that our website can dynamically present you with a personalized browsing experience and our customer support agents can provide you with contextual customer support.";1;;true

Configuring Spartacus for Intelligent Selling Services for SAP Commerce Cloud

You can carry out all of the following steps after you have set up your Spartacus Storefront. For more information, see Building the Spartacus Storefront from Libraries.

Install the Intelligent Selling Services library by running the following command from within the root directory of your storefront app:
```
 npm i @spartacus/cds
```
Import the Intelligent Selling Services module by adding the following line below the existing import statements at the top of app.module.ts:
```
 import { CdsModule } from '@spartacus/cds';
```
Add the CdsModule to app.module.ts.

The following is an example:
```
 @NgModule({
   imports: [
     CdsModule.forRoot({
       cds: {
         tenant: 'my-tenant',
         baseUrl: 'https://api.us.context.cloud.sap',
         endpoints: {
           strategyProducts: '/strategy/${tenant}/strategies/${strategyId}/products',
         },
         merchandising: {
           defaultCarouselViewportThreshold: 80,
         },
         profileTag: {
           javascriptUrl: 'https://tag.static.us.context.cloud.sap/js/profile-tag.js',
           configUrl:
             'https://tag.static.stage.context.cloud.sap/config/my-config123',
         },
       },
     }),
     ...
```
The following is a summary of the parameters of the CdsModule:
- tenant: Set this to your testing or production tenant, as required. For more information, see Tenant Provisioning.
- baseUrl: Replace the value shown in the example with the base URL of your Intelligent Selling Services environment.
- strategyProducts: Set this value as shown in the example.
- defaultCarouselViewportThreshold: With Commerce Cloud 1905.14 or newer, you can configure the percentage of the merchandising carousel that needs to be in the viewport for carousel view events to be sent to Intelligent Selling Services. If you are using an older version of Commerce Cloud, you can use this setting to provide the same functionality, but it will be applied to all carousels in the storefront, rather than individual carousels that you specify. If no value is provided, a default of 80% is used. In this case, 80% of the carousel needs to be in the viewport for view events to trigger.
- javascriptUrl: Specify the URL of the Profile Tag version you wish to use. It is recommended that you use the URL for the latest version of Profile Tag (for example, http://tag.static.us.context.cloud.sap/js/profile-tag.js). For more information, see Deciding Which Profile Tag Link to Use on the SAP Help Portal.
- configUrl: Specify the URL of the Profile Tag configuration that you have created in Intelligent Selling Services. For more information, see Profile Tag Overview on the SAP Help Portal.
- allowInsecureCookies: This is an optional parameter (not show in the example above) that specifies whether Profile Tag should set insecure cookies. The default value is false. If you are running on HTTP, set this parameter to true. For example, if you are using a local back end, allowInsecureCookies must be set to true. In production, it should always be set to false.
- gtmId: This is an optional parameter (not show in the example above) that is used to integrate Profile Tag with Google Tag Manager. For more information, see Profile Tag on the SAP Help Portal.

Profile Tag

To enable Profile Tag, create a CMSFlexComponent called ProfileTagComponent in the catalog, and place it in the footer. You can do this by importing the following ImpEx:

$contentCatalog=electronics-spaContentCatalog
$contentCV=catalogVersion(CatalogVersion.catalog(Catalog.id[default=$contentCatalog]),CatalogVersion.version[default=Staged])[default=$contentCatalog:Staged]
INSERT_UPDATE CMSFlexComponent;$contentCV[unique=true];uid[unique=true];name;flexType;&componentRef;
;;ProfileTagComponent;ProfileTag Spartacus Component;ProfileTagComponent;ProfileTagComponent;

INSERT_UPDATE ContentSlot;$contentCV[unique=true];uid[unique=true];cmsComponents(uid, $contentCV)[mode=append]
;;FooterSlot;ProfileTagComponent

This ImpEx creates the component in the Staged catalog. To publish it, run a sync, or replace Staged with Online in the ImpEx.

Merchandising

Merchandising carousels enable a Spartacus storefront to display the results of Merchandising in the form of a product carousel.

For more information, see Merchandising and Merchandising Module on the SAP Help Portal.

Requirements for Enabling Merchandising

Merchandising carousels require the merchandisingaddon and profiletagaddon extensions. Once you install the extensions, follow the steps in Merchandising Configuration Setup and Catalog Synchronization Configuration to synchronize a product catalog with Intelligent Selling Services.

It is also recommended to follow the instructions in Product Directory Configuration.

Adding a Merchandising Carousel with ImpEx

If you know your strategyId, you can add a Merchandising carousel through ImpEx. The following is an example:

# Homepage carousel
# Create the CMS Component
INSERT_UPDATE MerchandisingCarouselComponent;$contentCV[unique=true];uid[unique=true];name;title;numberToDisplay;strategy;&componentRef
;;HomepageE2EMerchandisingCarousel;Homepage E2E Merchandising Carousel;Homepage E2E Merchandising Carousel;10;00000000-0000-0000-0000-000000000000;HomepageE2EMerchandisingCarousel

# Add the component to the slot
INSERT_UPDATE ContentSlot;$contentCV[unique=true];uid[unique=true];cmsComponents(uid,$contentCV)
;;Section2CSlot-Homepage;HomepageE2EMerchandisingCarousel

# Category Page carousel
# Create the CMS Component
INSERT_UPDATE MerchandisingCarouselComponent;$contentCV[unique=true];uid[unique=true];name;title;numberToDisplay;strategy;&componentRef
;;CategoryPageE2EMerchandisingCarousel;Category Page E2E Merchandising Carousel;Category Page E2E Merchandising Carousel;10;00000000-0000-0000-0000-000000000000;CategoryPageE2EMerchandisingCarousel

# Add the component to the slot
INSERT_UPDATE ContentSlot;$contentCV[unique=true];uid[unique=true];cmsComponents(uid,$contentCV)
;;BottomHeaderSlot;CategoryPageE2EMerchandisingCarousel

# SLR Page carousel
# Create the CMS Component
INSERT_UPDATE MerchandisingCarouselComponent;$contentCV[unique=true];uid[unique=true];name;title;numberToDisplay;strategy;&componentRef
;;SLRCategoryPageE2EMerchandisingCarousel;SLR Category Page E2E Merchandising Carousel;SLR Category Page E2E Merchandising Carousel;10;00000000-0000-0000-0000-000000000000;SLRCategoryPageE2EMerchandisingCarousel

# Add the component to the slot
INSERT_UPDATE ContentSlot;$contentCV[unique=true];uid[unique=true];cmsComponents(uid,$contentCV)
;;SLRCamerasBottomHeaderSlot;SLRCategoryPageE2EMerchandisingCarousel

Note: The above ImpEx includes examples of locations where you can create and place the carousel in a slot, but you are not limited to these locations. You can place the CMS component in any slot that allows it.

Adding a Merchandising Carousel with SmartEdit

If you have followed the SmartEdit Setup Instructions for Spartacus, you can use SmartEdit to add a Merchandising carousel to a page, as follows:

Launch SmartEdit.
Edit the page you want to add a Merchandising carousel to.
Click the + Component button in SmartEdit.

You should see the SAP CONTEXT-DRIVEN MERCHANDISING carousel component. If you do not see it, use the search box.
Drag and drop the component onto a content slot on the page.

If the component does not drop in the Basic Edit mode, switch to the Advanced Edit mode using the dropdown in SmartEdit.
Fill in the fields of the configuration window that appears.

For the Number to Display field, specify the number of products you wish to display in the carousel. If the number of products exceeds the size of the carousel, the user will need to use scrolling arrows to see all products.

For the Scroll Type field, the only available scroll type is one. This enables the user to scroll the products one by one upon clicking the scrolling arrow.

For the Strategy field, select a configured Merchandising strategy to be used in the carousel.

For the Viewport Percentage field, enter the percentage of the carousel that needs to be in the viewport for carousel view events to be sent to Intelligent Selling Services.

Note: This configuration option is only available in Commerce Cloud version 1905.14 or newer. If you are using an older version of Commerce Cloud, you can use this setting to provide the same functionality, but it will be applied to all carousels in the storefront, rather than individual carousels that you specify.
Click Save for the Merchandising carousel to appear on the page you are editing.

Intelligent Selling Services for SAP Commerce Cloud Shell Application

Note: The Intelligent Selling Services Shell Application is for developers who are contributing to the Spartacus library sources. In other words, it is only available if you have cloned the Spartacus library sources and are working with a contributor set-up of Spartacus. For more information, see Contributor Setup

The following steps describe how to run the Intelligent Selling Services Shell Application:

Run the following command to execute the library builds:
```
 yarn build:core:lib:cds
```
Run the following command to start the shell:
```
 yarn start:cds
```
Run the following command to perform unit tests:
```
 yarn test:cds
```
When you run these commands, the browser opens, and you can see the progress of the tests with detailed information, including whether the tests pass.
Run the following command to perform end-to-end tests. You can do this either manually or automatically.

To run the tests manually, run the following commands:
```
 yarn start:cds
 yarn e2e:cy:cds:run:vendor
```
Note: To run the end-to-end test in headless mode, make sure you have your Spartacus instance running before executing the end-to-end command.

To run the tests automatically, run the following command:
```
 yarn e2e:cy:cds:start-open
```
Note: When using this command, you do not need to separately start a Spartacus instance; it is already done as part of the command. To run the Cypress end-to-end tests for Intelligent Selling Services in Spartacus, select merchandising-carousel.e2e-spec.ts in the Cypress user interface.

Other Commands for Intelligent Selling Services for SAP Commerce Cloud

All other Intelligent Selling Services commands have :cds as part of their name, and can be found in the package.json file of the Spartacus source code.