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.
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:
- Log in to Backoffice as an administrator.
- In the left sidebar of Backoffice, select WCMS ––> Component.
- Use the advanced search to find component with ID: StoreFinderLink
- 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.