Frequently Asked Questions - intershop/intershop-pwa GitHub Wiki
Deployment Scenarios For Angular Applications
General Questions
What Is the Intershop PWA and What Are Its Components?
The Intershop Progressive Web App is a REST API based storefront client built on top of the Intershop Commerce Management server version 7.10. This means that the communication between the Angular-based storefront and the Intershop Commerce Management works exclusively via REST.
The PWA itself consists of templates, components and services. Templates contain the HTML that is rendered for the browser and display the user interface. Services implement the business functionality using TypeScript. Components are mostly small, independent bridges between the templates and services. They prepare data for display in templates and collect input from the user to interact with the services. Multiple components and their respective templates are assembled to pages.
Please visit Software Architecture for further details.
Which Changes Are/Were Made in Which Version of the PWA?
The Intershop Progressive Web App is under continuous development. To get an overview over major changes that are applied in each version, please visit PWA Migrations.
How to Migrate to a Newer Version of the PWA?
To get an overview of PWA migration, please visit Support Article - PWA Migration Guide.
What to Do If a Bug Occurs in the PWA?
First of all, please check the Intershop Progressive Web App Feature List Overview - Intershop Progressive Web App Feature Lists. If this does not help, please contact the Intershop support by opening a ticket for the bug.
What Are the System Requirements For the Intershop Progressive Web App?
The system requirements for multiple different versions of the Intershop Progressive Web App can be found at Overview - Intershop Progressive Web App System Requirements.
Which Payment Methods and Connectors Are Supported in the PWA?
The PWA supports the Concardis-Payment-Connector.
All payment methods that do not rely on their own user interface, such as PayPal, should work. However, for credit cards, further customization to the project are necessary.
Please visit Public Release Note - Concardis Service Connector 1 and Overview - Intershop Progressive Web App System Requirements for further details on the available payment methods in the PWA.
How to Setup the PWA on a Local Machine?
For a detailed overview of the steps to set up the Intershop Progressive Web App on a local machine, please visit Guide - Intershop Progressive Web App - Getting Started.
Is it Possible to Contribute to the Intershop Progressive Web App?
Yes, any kind of contribution is appreciated. Please visit Guide - Intershop Progressive Web App - Contributing to the Intershop Progressive Web App for further details.
How is the Intershop PWA Project Structured?
To get a detailed overview of the Intershop Progressive Web App structure, please visit Concept - Intershop Progressive Web App - Project Structure.
PWA Functionality
Is It Possible to Implement Functionalities in the PWA that Are Available in the Responsive Starter Store?
The PWA is still under development and therefore some features that are available in the responsive starter store are not yet included. These functions must be implemented by yourself for now.
What Is the Role of the Traditional Web Adapter in the PWA?
In the PWA, the web adapter is used for handling and caching REST calls. It also delivers back-office CMS content components, such as images, to the PWA. The PWA is not aware of the web adapter.
Is It Possible to Manage PWA Localization Keys in the Back Office?
The management of PWA localization keys in the back office is not yet implemented. Please visit Concept - Intershop Progressive Web App - Localization for further details.
Why Is a User Not Redirected to a 404 Error Page Even If the Console Throws a 404 Error?
Redirects are not part of the Intershop CaaS environments. Therefore, custom application code must generate the error pages and redirects.
Are There Plans to Include a Design View Capability in a PWA Setup?
There are plans to integrate a design view into the PWA, but there is currently no release date.
How to Integrate CMS Into the Intershop Progressive Web App?
To get an overview of the CMS integration into the Intershop Progressive Web App, please visit Concept - Intershop Progressive Web App - CMS Integration.
How Does the PWA Improve the SEO?
The PWA improves SEO by using Universal for pre-rendering complete pages. This way, the PWA is able to respond to web crawlers with full indexable page responses.
Additionally, the 'express-robots-txt' library is used in the express.js server to provide a response to robots.txt for web crawlers.
The PWA also uses the library '@ngx-meta/core' to set tags for title, description, robots, canonical links and open graph information in page headers.
Please visit Search Engine Optimization SEO for further details.
Is Single Sign-On Supported in the PWA?
Yes, the Intershop PWA support SSO with the library 'angular-oauth2oidc'. After the ICM setup with the identity provider, the IdentitiyProvider interface that is provided in the IdentityProviderModule has to be added.
The configuration can be added to the Angular CLI environment files:
identityProvider: 'MyProvider',
identityProviders: {
'MyProvider': {
type: 'auth0',
domain: 'some-domain.auth0.com',
clientID: 'ASDF12345',
}
},
The configuration should be provided to the SSR process via environment variables. The usage of identity providers can also be set in the multi-channel configuration.
Please visit Single Sign-On (SSO) for PWA for PWA for further details.
Why is the selected language lost after a page refresh?
The Intershop PWA is currently not representing language or locale information in its path or routing information. This will lead to loosing this information on page refresh and the fallback to the default language.
The basic idea for the PWAs language representation are different domains for the different languages, e.g. www.mybrand.com for English and www.mybrand.de or de.mybrand.com for the German version. With Multi-Site Handling (see Multi Channel Context Routing) this is then either handled with different PWA deployments with different default languages or with one PWA deployment that is initialized with different languages by the nginx based on the incoming domain.
Why is the preferred language of a user, that can be configured in ICM, not considered in the PWA?
Handling the preferred language of a user is currently not implemented in the PWA.
While setting a preferred language on the registration page and changing the preferred language in the profile would work handling the language switching itself on login had some problems especially with the checkout login (internal issue ISREST-891). For this reason and for further considerations of the preferred language handling in language specific Multi-Site installations this functionality was not finished yet.
An alternative idea for the PWA is setting the shop language based on the browsers language settings (see #104).
Why are compared products lost after a page refresh?
The PWA is intended to run as a Single Page Application without any additional page load or page refresh after the initial page load. In this scenario the compared products information is saved in the PWAs state management. Since this state management information is not persisted by default it gets lost with any page refresh. While other data will be re-fetched from the ICM server via REST API, the compared products are only saved on the client side and therefore lost.
The browsers Local Storage could be a place to persist this information and re-fetch it after a page reload (e.g. via meta reducer localStorageSaveMeta). But this is currently not implemented.
PWA Configuration
Please visit Configuration for further details.
What happened to my environment.local.ts since PWA 1.0?
After upgrading to PWA 1.0 I get errors when trying to use my local PWA configuration in Angular CLI tooling. Errors like:
Error: Configuration 'local' is not set in the workspace.
Type '{ defaultDeviceType: "desktop"; icmBaseURL: string; icmChannel: string; theme: string; features: ("compare" | "rating" | "recently" | "advancedVariationHandling" | "businessCustomerRegistration" | ... 8 more ... | "wishlists")[]; ... 22 more ...; dataRetention: DataRetentionPolicy; }' is not assignable to type 'Environment'.
Object literal may only specify known properties, and 'theme' does not exist in type 'Environment'.
are hints that the underlying environment model has changed and your configuration is not assignment compatible anymore. As stated in Development Environment - Development Server, please use environment.development.ts for all local dev environment deviations from production configuration.
Is It Possible to Perform Configurations During Runtime?
Yes, it is possible to perform some configurations during runtime. The default values of these runtime settings can be set via the environment.ts file. These settings can be overridden by NgRx during runtime.
Everything managed in the NgRx state is accumulated on the server side and sent to the client side with the initial HTML response. These properties can be accessed via StatePropertiesService.
How to Connect an ICM to the PWA?
This can be achieved by modifying environment files or by setting the environment variable ICM_BASE_URL for the process running the Node.js server.
How to Statically Direct One Deployment to a Specific REST Endpoint Of the ICM?
This can be done by setting the properties icmChannel and icmApplication in the Angular CLI environment or the environment variables ICM_CHANNEL and ICM_APPLICATION.
How to Programmatically Enable/Disable Specific Functionalities in the PWA?
This can be done using feature toggles such as guards, directives, pipes and services.
How to Set a Default Language and Add Other Languages to the PWA?
The default language can be set simply by changing the order of the locales in the Angular CLI environment files. The first locale is set as the default.
It is also possible to set the default locale dynamically by using the URL parameter lang when rewriting a URL.
How to add a new language is described in Configuration - Extend Locales.
Is There Any Way to Extend the Logging?
Yes, to make the express.js image log extended information to the console, supply the environment variable LOGGING=true. Please visit Logging for further details.
Localization
Please visit Localization for further details.
Is Pluralization Possible in the PWA?
Yes, pluralization is supported in the PWA. This requires changes to the localization file, the '*.component.html' file and the parameter settings in the '*.component.html' and '*.component.ts' files.
How to Generate Localization Files?
Existing localization properties of the RSS can be converted to proper JSON files via a gradle plugin.
Is There a Way to Easily Keep the Localization Files Clean?
Yes, the PWA provides a script that is saved under scripts/clean-up-localizations.js and can be run with npm run clean-localizations to remove all unused localization keys from the default localization file and generate localization files for the other available language files.
Localization keys that are not explicitly used, such as dynamically created keys or error keys from REST calls, are handled separately. Their patterns are searched in all the localization keys of the default localization file and all matches will be included in the new cleaned up file. Therefore, additional patterns must be added for additional keys used in this way.
Styling and Behavior
Please visit Styling & Behavior for further details.
Where to Change the Styling?
The Styling can be configured in the project's global /src/themes/main.scss file. It is referenced in the angular.json file and compiled automatically. There are almost no component specific styleUrls or style properties in the PWA.
Which Bootstrap Version Is in Use?
The PWA is built on the latest version of Bootstrap 4, so the styling is based on Sass. Ng-bootstrap provides useful Bootstrap widgets that work best with the styling taken from the Responsive Starter Store.
Testing the PWA
Please visit Testing the PWA for further details.
Which Tests Are Available in the PWA?
The PWA offers the capabilities for unit tests, module tests, integration tests and end-to-end tests. Unit tests display the behavior of a single unit of code, are very time efficient and should be used for most testing purposes. Module tests check the behavior when multiple components are connected. The integration tests run the application as a whole but mock out the ICM REST responses. Finally, the full end-to-end tests take the most time since nothing is mocked out and the PWA runs against the ICM.
Jest is used for unit tests and module tests, while Cypress is used for integration tests and end-to-end tests.
Where Are the Test Files Located?
Unit and module tests are closely located next to the production source code in the src folder. Integration tests and end-to-end tests are located in cypress/integration/specs, while the corresponding PageObjects can be found in cypress/integration/pages.
How Does the PWA Differ From Standard Angular Test Frameworks?
Angular projects are setup by default with 'Jasmine' and 'Karma Runner' for unit and module tests as well as 'Protractor' for end-to-end tests.
However, the PWA uses 'Jest' for unit and module tests. With 'Jest' no real browser has to be booted up as with 'Jasmine' or 'Karma Runner'. Additionally, 'Jest' offers an interactive command line interface and provides integrations for Visual Studio Code as well as functionality for Snapshot Testing.
For end-to-end tests, 'Cypress' is used with a 'PageObject' pattern, as 'Protractor' tests are usually very fragile against network latency and offer limited functionalities. 'Cypress' on the other hand, runs directly in the browser, provides access to application internals and page snapshots for debugging.
CMS Integration
How to Integrate the CMS Resources Into the PWA?
Calling the /cms resource lists all available CMS sub resources for the various CMS artifacts. Using the API shown below, a client can retrieve a composition of involved CMS objects. These must be interpreted and rendered by the client itself. This is done by mapping each element onto an Angular specific render component. Please visit CMS Integration for further details.
Is There Any Way to Use a Third Party CMS For the PWA?
It should be possible to integrate an external third party CMS that provides its own REST API instead of the ICM CMS. Combinations would also be possible. If an external API needs to be integrated, the native Angular httpClient must be used for the REST calls instead of the PWAs apiService. Additionally, the mapping of the content needs to be handled in way that it fits to the external CMS. Please visit CMS Integration for further details.
Does the PWA Support URL Rewriting?
Yes, the PWA supports URL rewriting by allowing to provide localized and SEO optimized URLs for categories and product detail pages. This feature is build on Angular's 'UrlMatcher' to parse routes and a custom pipe to generate them.
Please visit URL Rewriting for further details.
Headless Application Type
Please visit Concept - Headless Application Type - intershop.REST for further details.
What Are the Advantages Of the Headless Application Type?
The headless application type is completely independent of the Responsive Starter Store. It supports B2C, B2B and mixed functionality via the REST API.
However, it is not suitable for storefront setups that are using a hybrid approach.
How to Distinguish Between a B2B and B2C Shop If No User is Logged in?
The intershop.REST application does not indicate whether an application is a B2C or B2B application. There is no such distinction anymore. It only matters how an application is used.
Therefore, the REST client must be configured using feature toggles to determine whether the client acts as a B2C or B2B client.
Are There Plans To Add Functionality to Delete a Customer via the intershop.REST Framework?
Since the PWA version 7.10.20.x there is a new BACKOFFICE REST API that allows backoffice users to delete a customer via REST.
For GDPR matters, the contact form can also be used by the end customer to request deletion of their own profile.
Hybrid Approach
Please visit Hybrid Approach for further details.
What Is the Hybrid Approach?
The Hybrid Approach means, running Angular and the classic storefront in parallel and switching seamlessly between the two. For example, a customer might start shopping in the Angular PWA while the checkout process is handled by the classic storefront. After the checkout is complete, the Angular storefront takes over again.
The main purpose of this approach is to enable the use of all PWA features while adding RSS features, since the PWA does not support all features available in the RSS.
How is It Decided Whether a Request Is a PWA or an ICM Request?
A mapping table is used to decide whether an incoming request should be handled by the PWA or by the ICM.
Is it Possible to Use the Hybrid Approach With the Headless Application Type?
No, the headless application type is not suitable for storefront setups that use the hybrid approach.
Is There a Way to Use RSS Features in the PWA?
Yes, it is possible to move available RSS functionality to the Angular storefront by migration.
Demo Servers
Is There a Demo Server For the PWA?
Yes, there is a demo server for the PWA. Please visit Reference - Demo Server for Intershop PWA for further details.
What Are the Steps to Set Up a Local Demo Server?
Please take a look at the Guide - Quick Project Setup and Support Article - How To Deploy a PWA Demo Server in Production Mode.
Please visit Building Blocks of the Intershop PWA Public Deployment for further details.
PWA Demo Server in Production Mode
What Are the Advantages of Nginx and Server Side Rendering?
Nginx enables easy caching of PWA server-side rendering responses, integration of the PageSpeed Module to access browser optimizations, and handling of multiple channels via URL parameters in conjunction with server-side rendering. Additionally, compression for downstream services becomes highly customizable. The Device type detection is able to ensure correct pre-rendering for a specific incoming user agent.
The server-rendering additionally improves SEO, enables safe and dynamic configuration of the PWA through URL parameters and the dynamic integration of specific RSS pages. Please visit Hybrid Approach for further details on the integration of specific RSS pages.
Is It Possible to Hide the ICM Backend?
Yes, the default deployment of the PWA uses this feature. To enable it, set the PROXY_ICM environment variable on the SSR container to a new URL. This way, traffic is routed trough a SSR container instead of being routed directly to the ICM. The express.js server proxies the requests.
After the Angular Universal pre-rendering is complete, all URLs referring to the ICM in use are replaced with URLs to the proxy.
Deployment Scenarios For Angular Applications
Please visit Deployment Scenarios for Angular Applications for further details.
What Type Of Deployment does the PWA use?
The default setup for the Intershop PWA is based on a browser-side rendering with on-demand server-side pre-rendering. The Angular Universal package is used for this. In addition to the client-side application, a server-side application is build. Its distribution is executed in a node environment. The server.js executable handles client requests on the server and pre-renders the content of the site. This way, the initial page response is mostly prepared and can be quickly displayed on the client side while the client-side application is booting up.
What are Service Workers?
Service Workers are automatically installed into client device browsers after the first visit to the shop and take over all the handling of the application on the client side. After installation, the service worker effectively disables server-side rendering for clients and invokes all rendering on the client himself. Browsers and crawlers that do not support JavaScript execution also receive the pre-rendered page responses from the SSR process.
How to Enable Service Workers?
It is possible to enable service workers by running node schematics/customization/service-worker true. Please visit Progressive Web App for further details.
State Management
How Does the PWA Manages States?
Please visit State Management for further details on how the PWA manages it's states.
Is It Possible to Request and Manipulate Entity Collections?
Yes, '@ngrx/entitiy' provides an API to manipulate and query entity collections.
Multi-Site Configuration
Please visit Multi-Site Handling for further details.
Why Is Multi-Site Rendering Important?
Thanks to multi-side rendering, it is possible to manage multiple sites with only one instance of the PWA and a reverse proxy running in front, instead of needing multiple PWA instances in combination with one nginx each. The PWA features means to dynamically configure ICM channel and application to determine the correct REST endpoint for each incoming top level request.
2.11.2 When Is It Possible to Combine Multiples Sites in a PWA? It is possible to run multiple sites e.g. for multiple countries or brands with one PWA as long as the underlying feature set is very similar. Features for different sites, like certain B2B features, can be enabled and disabled via feature toggles.
Please take a look at the documentation for multi-site configuration for nginx on GitHub.
If the feature set is significantly different for some sites, it is recommended to use multiple PWA instances.
Is It Possible to Create Multiple Pages With a Different Layout?
Please take a look at the PWA sources. The styles/pages folder shows how the layout is done, while the app/pages folder shows how the pages and their components are created.
Kubernetes
What Is The Suggested Underlying Stack?
Intershop uses Kubernetes, an open-source platform that is used for containerized workloads and services. It provides a container-centric management environment and coordinates compute, networking and storage infrastructure on behalf of user workloads.
This provides much of the simplicity of Platform as a Service with the flexibility of Infrastructure as a Service and enables portability between infrastructure providers.
(Translated from the Kubernetes Website)
Why Is It Necessary to Create Redundancy on PWA Level?
It is recommended to run three Kubernetes pods, each deploying a PWA instance, to ensure the reliability and also no downtimes during update processes.
How Does the PWA Optimize Costs?
The recommended way is to run one PWA in three Kubernetes pods. This approach is also scalable later on.
Third Party Services
Is It Possible to Integrate an Adobe AEM Connector Into the PWA?
Currently, there is no solution for this and there are no plans to implement such a connector for newer versions of the PWA.
Is It Possible to Use Akamai For Caching?
There are plans to include Akamai support in the future, but there is no release date yet. The PWA team will consider feedback on this.