CloudNir

Home » Spartacus Features

Spartacus Features

This is a landing page for grouping together Spartacus Features topics. The Spartacus Features topics include the following:

  • Anonymous Consent
  • Assisted Service Module
  • Consignment Tracking
  • Coupons
  • Store Locator
  • Token Revocation

Anonymous Consent (DRAFT)

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

Overview

Anonymous Consent Management gives anonymous users control over the tracking of their data. Anonymous users can grant or decline their consent for applications that collect and process personal data. For more, refer to the Anonymous Consent Management on SAP Help Portal

Requirements

Back End Requirements

As anonymous consent uses a custom header x-anonymous-consents, this needs to be configured on the back end by adding it to the following properties:

  • corsfilter.ycommercewebservices.allowedHeaders
  • corsfilter.ycommercewebservices.exposedHeaders
  • corsfilter.assistedservicewebservices.allowedHeaders – if ASM is being used
  • corsfilter.assistedservicewebservices.exposedHeaders – if ASM is being used

Consent Data

Besides having consent defined on the back end, they need to be marked as exposed, which can be done by executing an impex file similar to this:

$siteUid=electronics-spa

INSERT_UPDATE ConsentTemplate;id[unique=true];name;description;version[unique=true];baseSite(uid)[unique=true,default=$siteUid];exposed

;PERSONALIZATION;”I approve to this sample PERSONALIZATION consent”;”This is a sample personalization consent description that will need to be updated or replaced.”;0;;true

;MARKETING_NEWSLETTER;”I approve to this sample MARKETING consent”;”This is a sample marketing consent description that will need to be updated or replaced, based on the valid registration consent required.”;0;;true

;STORE_USER_INFORMATION;”I approve to this sample STORE USER INFORMATION consent”;”This is a sample store user information consent description that will need to be updated or replaced.”;0;;true

Notice that the last column named exposed is set to true for the consents that should be exposed to the anonymous users.

CMS Components

The anonymous consent banner, and the link in the footer that opens the anonymous consent dialog, are driven by CMS. To have these CMS components, an ImpEx similar to this can be used:

$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;restrictions(uid,$contentCV)

;;AnonymousConsentManagementBannerComponent;Anonymous Consent Management Banner Component;AnonymousConsentManagementBannerComponent;AnonymousConsentManagementBannerComponent;anonymousUserRestriction

;;AnonymousConsentOpenDialogComponent;Anonymous Consent Open Dialog Component;AnonymousConsentOpenDialogComponent;AnonymousConsentOpenDialogComponent;anonymousUserRestriction

Having these CMS components alone is not enough to enable the whole anonymous consent feature. Please see Enabling Anonymous Consent section.

Footer notice

Previously, the footer-navigation.component.html was tightly coupled with the footer notice message, which is now a CMSParagraphComponent that should also be added like this:

$contentCatalog=electronics-spaContentCatalog

$contentCV=catalogVersion(CatalogVersion.catalog(Catalog.id[default=$contentCatalog]),CatalogVersion.version[default=Staged])[default=$contentCatalog:Staged]

INSERT_UPDATE CMSParagraphComponent;$contentCV[unique=true];uid[unique=true];name;&componentRef;

;;NoticeTextParagraph;Notice Text Paragraph;NoticeTextParagraph;

UPDATE ContentSlot;$contentCV[unique=true];uid[unique=true];cmsComponents(uid, $contentCV)

;;FooterSlot;FooterNavigationComponent,AnonymousConsentOpenDialogComponent,NoticeTextParagraph,AnonymousConsentManagementBannerComponent

Along with the NoticeTextParagraph CMS component you should also update the localized properties files with a sample text such as this example:

CMSParagraphComponent.NoticeTextParagraph.content=”<div class=””cx-notice””>Copyright © 2019 SAP SE or an SAP affiliate company. All rights reserved.</div>”

After changing the *.properties files, don’t forget to run ant build and the ant initialize commands.

Warning: to preserve backwards compatibility, the notice will still be displayed if the Anonymous Consent feature is disabled. However, if you add the CMS NoticeTextParagraph component (and have the Anonymous Consent feature disabled), you will see duplicated notice, like shown on the screen shot below:

In this case, you can either enable Anonymous Consent feature or remove the NoticeTextParagraph CMS component.

Enabling Anonymous Consent

To enable anonymous consent in Spartacus, you need to enable the anonymousConsents feature in your app.module.ts, i.e.:

B2cStorefrontModule.withConfig({

features: {

  …

  anonymousConsents: true,

  …

},

}

Configuring Anonymous Consent

Spartacus offers some configuration options that are encapsulated in anonymousConsents configuration object. The following options are available:

  • registerConsent – specify a consent template ID that should be rendered on the registration page. By default, MARKETING_NEWSLETTER is being rendered.
  • showLegalDescriptionInDialog – set to false if the legal description shouldn’t be visible on the anonymous consents dialog. By default, this has true value.
  • requiredConsents – specify an array of consent template IDs that are going to be required for the end users. These consents are given by default, and users can’t toggle them. By default, this array is empty.
  • consentManagementPage.showAnonymousConsents – specify whether to show anonymous consents on the registered consent management page. By default, this is set to true, and setting it to false will hide all consents from consents management page that have exposed property set to true. In case you don’t want to hide all anonymous consents from the consents management page, refer to consentManagementPage.hideConsents below.
  • consentManagementPage.hideConsents – an array of consent template IDs that should be hidden on the consents management page. By default, this array is empty, and adding consent template IDs to it will hide them from the consents management page.

Changing UI Labels

In order to customize any UI message on the banner or in the dialog, you can refer to our i18n guide on how to override the existing translation keys.

Extending Anonymous Consent

No special extensibility is available for this feature.

Assisted Service Module (DRAFT)

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

Overview

Assisted Service Module (ASM) enables customer service personnel to provide real-time customer sales and service support using the storefront. For more information, refer to the ASM section on SAP Help Portal

Spartacus now supports the ASM functionality that allows customer emulation by sales support agents through the Spartacus storefront.

Requirements

For more information on to setup and configure ASM on your SAP Commerce Cloud, refer to the ASM section on SAP Help Portal.

Here are a few setup steps that are important and/or specific to get ASM working with Spartacus:

ASM Back End Requirements

ASM in Spartacus requires SAP Commerce Cloud version 1905.5 or newer. The minimum version of 1905.5 is required to enable CORS in the assistedservicewebservices endpoints.

The ASM feature in Spartacus requires the following extensions:

  • assistedservicewebservices Extension
  • assistedservicestorefront AddOn

Granting asagentgroup CMS Permissions

The user group asagentgroup needs specific rights to read CMS data from OCC.

Option 1: Initialize from scratch with 1905.5

If you start from scratch and initialize your SAP Commerce Cloud system with version 1905.5 or newer, asagentgroup will get the required permissions to use cms data via Spartacus and OCC. There is no additional step to do.

Option 2: Manual import in impex console

If you upgrade from an earlier version than 1905.5, you need to grant the asagentgroup permissions by importing this impex data via the impex console:

# Access rights for asagentgroup

# – These are needed for rendering (cmsoccaddon).

$START_USERRIGHTS;;;;;;;;;

Type;UID;MemberOfGroups;Password;Target;read;change;create;remove;change_perm

UserGroup;asagentgroup;;;;;;;;

# general

;;;;Item;+;;;;;

;;;;Type;+;;;;;

# access rights for Products, Store, Site and Catalogs

;;;;Product;+;;;;;

;;;;Category;+;;;;;

;;;;VariantType;+;;;;;

;;;;BaseSite;+;;;;;

;;;;BaseStore;+;;;;;

;;;;Catalog;+;;;;;

;;;;CatalogVersion;+;;;;;

;;;;ContentCatalog;+;;;;;

;;;;MediaContainer;+;-;-;-;-;

;;;;MediaContext;+;-;-;-;-;

;;;;MediaFormat;+;-;-;-;-;

;;;;MediaFormatMapping;+;-;-;-;-;

# cms2 items

;;;;CMSItem;+;-;-;-;-;

$END_USERRIGHTS;;;;;

CORS Configuration

The assistedservicewebservices extension requires CORS configuration, which is possible since SAP Commerce Cloud version 1905.5.
The cors configurations for assistedservicewebservices have default values specified in the project.properties file of the assistedservicewebservices. At the time of writing these lines, the default values are:

corsfilter.assistedservicewebservices.allowedOrigins=http://localhost:4200 https://localhost:4200

corsfilter.assistedservicewebservices.allowedMethods=GET HEAD OPTIONS PATCH PUT POST DELETE

corsfilter.assistedservicewebservices.allowedHeaders=origin content-type accept authorization

Customizing CORS Configuration

CORS configurations are customized by overriding the default configuration via your local.properties file.

Since configurations are overridden in local.properties, if you want to add a configuration element without losing the default value, you need to add all the defaults in addition to the new element. For example, to add ‘my-new-header’ in the allowed header list in addition to the default ones, you need to add this in local.properties:

corsfilter.assistedservicewebservices.allowedHeaders=origin content-type accept authorization my-new-header.

To customize allowedMethods and allowedHeaders you should add to the default values. To customize allowedOrigins, you will need to override the value with one that is relevant for your environment.

allowedOrigins

You need to customize the allowedOrigins property for assistedservicewebservices with host names that are relevant to your environment. As mentioned above, this is done by adding the propery yout local.properties with a new value:

corsfilter.assistedservicewebservices.allowedOrigins=https://my-new-host:4200

For development purposes only, the value can be a wildcard:

corsfilter.assistedservicewebservices.allowedOrigins=*

Bear in mind this wildcard configuration is flexible for development environments but it is unsecured. A more restrictive configuration is required for production use.

Invoke the ASM UI in the storefront

To invoke the ASM UI in the storefront, add the ?asm=true suffix to the url. For example, with the sample store, you can invoke the ASM UI on the home page with this url.

https://{hostname}/electronics-spa/en/USD/?asm=true

Update custom services to support ASM.

If you use a custom service that extends one of these classes:

  • UserService
  • UserAddressService
  • UserConsentService
  • UserOrderService
  • UserPaymentService

You need to update their constructor in order to support ASM in your storefront.

If during customer emulation the storefront displays the error message: Cannot find user with propertyValue ‘current’, it is very likely that you use custom services that need to be updated to support ASM.

The update consists of adding a dependency to AuthService in the constructor and pass it down to super(). The constructors that don’t have AuthService are now deprecated.

Beyond the constructor update, you may need to update your custom functions to support ASM as well. See the section called How to write ASM compatible code for details.

Update UserService Subclasses

Custom service

export class CustomUserService extends UserService {

  constructor(store: Store<StateWithUser | StateWithProcess<void>>) {

    super(store);

  }

}

Custom service updated to support ASM.

export class CustomUserService extends UserService {

  constructor(

    store: Store<StateWithUser | StateWithProcess<void>>,

    authService: AuthService

  ) {

    super(store, authService);

  }

}

Update UserAddressService Subclasses

Custom service

export class CustomUserAddressService extends UserAddressService {

  constructor(protected store: Store<StateWithUser | StateWithProcess<void>>) {

    super(store);

  }

}

Custom service updated to support ASM.

export class CustomUserAddressService extends UserAddressService {

  constructor(

    protected store: Store<StateWithUser | StateWithProcess<void>>,

    protected authService: AuthService

  ) {

    super(store, authService);

  }

}

Update UserConsentService Subclasses

Custom service

export class CustomUserConsentService extends UserConsentService {

  constructor(protected store: Store<StateWithUser | StateWithProcess<void>>) {

    super(store);

  }

}

Custom service updated to support ASM.

export class CustomUserConsentService extends UserConsentService {

  constructor(

    protected store: Store<StateWithUser | StateWithProcess<void>>,

    protected authService: AuthService

  ) {

    super(store, authService);

  }

}

Update UserOrderService Subclasses

Custom service

export class CustomUserOrderService extends UserOrderService {

  constructor(protected store: Store<StateWithUser | StateWithProcess<void>>) {

    super(store);

  }

}

Custom service updated to support ASM.

export class CustomUserOrderService extends UserOrderService {

  constructor(

    protected store: Store<StateWithUser | StateWithProcess<void>>,

    protected authService: AuthService

  ) {

    super(store, authService);

  }

}

Update UserPaymentService Subclasses

Custom service

export class CustomUserPaymentService extends UserPaymentService {

  constructor(protected store: Store<StateWithUser | StateWithProcess<void>>) {

    super(store);

  }

}

Custom service updated to support ASM.

export class CustomUserPaymentService extends UserPaymentService {

  constructor(

    protected store: Store<StateWithUser | StateWithProcess<void>>,

    protected authService: AuthService

  ) {

    super(store, authService);

  }

}

How to write ASM compatible code.

Writing ASM compatible code is all about using the function getOccUserId() from the AuthService to determine the userId used in occ calls. This is typically done in a service that dispatches and action containing the userId in the payload.

Before ASM was released, the occ userId in requests on the behalf of an authenticated user was the special occ user “current”, represented by the constant OCC_USER_ID_CURRENT, like in this example:

  load(): void {

    this.store.dispatch(new UserActions.LoadUserDetails(OCC_USER_ID_CURRENT));

  }

Now that Spartacus supports ASM, the correct way to determine the occ userId is to call AuthService.getOccUserId(). When we update the previous example, we get:

  load(): void {

    this.authService

      .getOccUserId()

      .pipe(take(1))

      .subscribe(occUserId =>

        this.store.dispatch(new UserActions.LoadUserDetails(occUserId))

      );

  }

The rule of thumb is, if OCC_USER_ID_CURRENT is used directly in a service, it should likely be replaced by a call to getOccUserId().

In order to support ASM, and potentially other features in the future, the facade services can’t simply use the “current” special userId when calling various actions. There needs to be some logic applied to determine the correct OCC userId to pass down to actions that will trigger a backend call.

Therefore, the logic to determine the correct OCC userId given the context is centralized in the AuthService function getOccUserId().

Configuring

Some ASM behaviors can be configures through Spartacus.

asm.agentSessionTimer.startingDelayInSeconds

The start time for the customer support agent session timer has a default value of 600 seconds (10 minutes). This can be configured. Specify the number of seconds for the timer staring delay via the property asm.agentSessionTimer.startingDelayInSeconds like so ( using the B2cStorefrontModule as an example ):

B2cStorefrontModule.withConfig({

  asm: {

    agentSessionTimer: {

      startingDelayInSeconds: 600

    }

  }

});

asm.customeSearch.maxResults

The number of results in the asm customer search can be customized in spartacus via the property asm.customeSearch.maxResults. You define it like this ( using the B2cStorefrontModule as an example ):

B2cStorefrontModule.withConfig({

  asm: {

    customeSearch: {

      maxResults: 20

    }

  }

});

Extending

No special extensibility is available for this feature.

Consignment Tracking

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

Overview

Customers can view consignment tracking information to know the real-time status of their packages.

On the order details page, if the consignment shows its status as Shipped, a Track Package button is viewable for this consignment. Click the Track Package button to get the tracking information for the selected consignment.

Requirements

The consignment tracking feature requires the consignmenttrackingoccaddon AddOn.

Note: You can use the consignmenttrackingmock extension to help with functional testing for consignment tracking. For more information, see consignmenttrackingmock Extension in the SAP Help Portal.

For more information in general about consignment tracking, see Consignment Tracking Architecture in the SAP Help Portal.

Enabling Consignment Tracking

Consignment tracking has a consignmentTracking feature flag that allows you to enable or disable the feature, as follows:

features: {

   consignmentTracking: true

}

Consignment tracking is enabled automatically for feature level 1.2 and above.

For more information on feature flags and feature levels, see Configuring Feature Flags.

Configuring

No special configuration is required.

Extending

No special extensibility is available for this feature.

Coupons (DRAFT)

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

Overview

When a coupon promotion has been created, customers apply the applicable coupon to activate the promotion during checkout to get discounts and/or rewards for their orders.

Requirements

The coupon feature requires the following extensions to work:

  • couponbackoffice Extension
  • couponfacades Extension
  • couponwebservices Extension

For more information, see Coupon Architecture in the SAP Help Portal.

Enabling Coupons

The coupon feature has corresponding CMS-component data in the back end that allows you to enable or disable the feature.

Configuring

No special configuration needed.

Coupons are managed using Backoffice. See Coupon Module for more information.

Extending

No special extensibility available for this feature.

Store Locator

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

Overview

The Spartacus store locator feature helps customers find brick-and-mortar retail locations. Customers can view a list of all stores, they can search for stores based on their location, or they can search for stores based on a postal code, a town, or an address that the customer provides.

If the customer chooses to Use My Location, and allows their device to access their current location, a list of the nearest stores is displayed, sorted by distance in kilometers. By selecting any store in the list, the customer can view store details, such as address, phone number, opening hours, and store features.

If the customer chooses to View All Stores, a list of all stores is displayed, sorted by country, and with the number of stores in each country shown in parentheses. When the customer selects a country, a list of all the stores in the selected country is displayed, along with the address for each store. Customers also have the option to Get Directions for a particular store, which opens Google Maps in a separate browser window with directions from the customer’s location to the selected store.

The customer can also search for the nearest stores by entering an address, a town, or a postal code in the search bar. The search results indicate the nearest stores, based on the location provided by the customer.

Configuring the Store Locator

The store locator is configured in default-store-finder-config.ts, as follows:

  googleMaps: {

    apiUrl: ‘https://maps.googleapis.com/maps/api/js’,

    apiKey: ‘GOOGLE_MAPS_API_KEY’,

    scale: 5,

    selectedMarkerScale: 17

}

The following is a description of the googleMaps parameters:

  • apiUrl takes the format of a string, and is the URL to Google Maps.
  • apiKey take the format of a string, and is the unique Google Maps API key that belongs to the store owner.
  • scale takes the format of a number, and sets the initial zoom when the map is displayed.
  • selectedMarkerScale takes the format of a number, and sets the zoom on the map when a store location is selected.

Enabling the Store Locator

The store locator is enabled by default.

Disabling the Store Locator

You can disable the store locator by removing the Find a Store link in the header, and by deleting the StoreFinder Page in Backoffice, as described in the following procedure:

  1. Log in to Backoffice as an administrator.
  2. In the left sidebar of Backoffice, select WCMS ––> Component.
  3. Use the advanced search to find component with ID: StoreFinderLink
  4. Select the one in the appropriate catalog and set its visibility to: false.

This removes the Find a Store link from the header.

  • In the left sidebar of Backoffice, select WCMS ––> Page.
  • Use the search bar to search for storefinder.
  • Select the StoreFinder Page that you wish to disable.
  • In the StoreFinder Page panel, click the Page Status dropdown list and select Deleted.
  • Click Save.

You have now disabled the store locator.

After you have disabled the store locator, if a customer tries to directly access the store locator URL, Spartacus returns a 404 error.

Further Reading

Consult the SAP Help Portal for more information on the following topics:

Token Revocation

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

Overview

When a user signs out of the storefront, Spartacus 1.4.0+ will request the revocation of the user authentication token so the OCC session is terminated. This is a security improvement.

Here is what to expect:

  • When a customer signs out of the storefron, a token revocation request is sent.
  • When an ASM customer support agent signs out, a token revocation request is sent.
  • When an a customer emulated wuth ASM signs out, a token revocation is not sent. The customer support agent’s token is used in emulation sessions and we only want to revoke it when the agent himself signs out.

If the token revocation request fails, Spartacus will fail silently since there is no action it can make to recover. For example requesting the revocation of an alreay expired token will result in a http 401 response. Even if the server sends an error response, Spartacus will fail silently.

Requirements

Spartacus

You need Spartacus v1.4.0

Backend

Token revocation is available on backends with version 1905.6 and above.

Spartacus 1.4.0+ can still be used with backends with a version lower than 1905.6. In Spartacus, token revocation will fail silently if the backend does not support it.

Under the hood, a backend that does not support token revocation will return an http 302 redirect response on a token revocation request. The backend’s behaviour on a request to a non-existing authorization-related endpoint is to return a 302 redirect code pointing to the login.jsp page.

Enabling Consignment Tracking

Token revocation in Spartacus is always enabled in v1.4.0+.

Configuring

No extra configuration is required.

Extending

No special extensibility is available for this feature.