Context-Driven Services Integration

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

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

For more information, see SAP Commerce Cloud, Context-Driven Services on the SAP Help Portal.


Table of Contents


Requirements

To integrate Context-Driven Services 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 Context-Driven Services in Spartacus

To enable Context-Driven Services in Spartacus, you need to configure both the Commerce Cloud back end, and the Spartacus front end.

Configuring the Back End for Context-Driven Services

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.

  1. 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.

  2. 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 SAP Commerce Cloud, Context-Driven Services tracking";"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 Context-Driven Services

If you are using Spartacus 3.2 or newer, you can install and configure the Context-Driven Services integration using Spartacus schematics. If you are using an older version of Spartacus, see Configuring Spartacus for Context-Driven Services in our archived documentation.

To take advantage of the automatic setup provided by Spartacus schematics, you need to first ensure that you are using Spartacus 3.2 or newer, and you also need to ensure that your storefront app adheres to the app structure introduced with Spartacus 3.2. For more information, see Reference App Structure.

After you have met these prerequisites, you can install the Context-Driven Services integration by running the following command:

ng add @spartacus/cds

After running the command, you are prompted to provide additional information, as follows:

  • tenant asks you to provide a tenant name (for example, my-tenant)
  • baseUrl asks you to provide the base URL for the Context-Driven Services back end (for example, https://my-tenant.api.us.context.cloud.sap)
  • profileTagLoadUrl is optional, and asks where to load the Profile Tag from (for example, https://tag.static.us.context.cloud.sap/js/profile-tag.js)
  • profileTagConfigUrl is optional, and asks for the Profile Tag configuration URL (for example, https://tag.static.stage.context.cloud.sap/config/my-config123)

After you have provided this information, the schematics configure the Context-Driven Services integration for Spartacus.

If you do not wish to use the schematics, you can create the Context-Driven Services module manually and import it into your application, as shown in the following example:

import { NgModule } from '@angular/core';
import { CdsConfig, CdsModule } from '@spartacus/cds';
import { provideConfig } from '@spartacus/core';

@NgModule({
  imports: [CdsModule.forRoot()],
  providers: [
    provideConfig(<CdsConfig>{
      cds: {
        tenant: 'my-tenant',
        baseUrl: 'https://my-tenant.api.us.context.cloud.sap',
        endpoints: {
          strategyProducts:
            '/strategy/${tenant}/strategies/${strategyId}/products',
        },
        merchandising: {
          defaultCarouselViewportThreshold: 80,
        },
      },
    }),
    provideConfig(<CdsConfig>{
      cds: {
        profileTag: {
          javascriptUrl:
            'https://tag.static.us.context.cloud.sap/js/profile-tag.js',
          configUrl:
            'https://tag.static.stage.context.cloud.sap/config/my-config123',
          allowInsecureCookies: true,
        },
      },
    }),
  ],
})
export class CdsFeatureModule {}

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 Context-Driven Services environment. In particular, replace my-tenant with your actual Context-Driven Services tenant ID, and also replace .us with .eu if you are working with the EU environment of Context-Driven Services.
  • 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 Context-Driven 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 Context-Driven 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.

Context-Driven Merchandising

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

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

Note: Using the Profile Tag Data Layer for Merchandising Carousel Events requires Spartacus version 2.1.0 or newer. For more information, see the following:

Requirements for Enabling Context-Driven Merchandising

Context-Driven 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 Context-Driven Services.

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

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.

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

  1. Launch SmartEdit.

  2. Edit the page you want to add a Merchandising carousel to.

  3. 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.

  4. 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.

  5. 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 Context-Driven 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.

  6. Click Save for the Merchandising carousel to appear on the page you are editing.

Context-Driven Services Shell Application

Note: The Context-Driven 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 Context-Driven Services Shell Application:

  1. Run the following command to execute the library builds:

     yarn build:core:lib:cds
    
  2. Run the following command to start the shell:

     yarn start:cds
    
  3. 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.

  4. 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 Context-Driven Services in Spartacus, select merchandising-carousel.e2e-spec.ts in the Cypress user interface.

Other Commands for Context-Driven Services

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

Limitations

Login flow is currently not fully supported.