Introduction
This article provides answers to some of the most frequently asked questions about the Progressive Web App (PWA).
References
Overview - Intershop Progressive Web App System Requirements
Guide - Intershop Progressive Web App - Contributing to the Intershop Progressive Web App
Support Article - How To Deploy a PWA Demo Server in Production Mode
FAQ
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 displays 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 of major changes that are applied in each version, please visit PWA Migrations.
How to Migrate to a Newer Version of the PWA?
To update to a newer PWA version, add the Intershop PWA GitHub repository as a second remote in the project and merge the latest release branch. See Support Article - PWA Migration Guide for further information.
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 is 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 for setting 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 (RSS) 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 Any Plans to Include a Design View Capability in a PWA Setup?
It is planned to integrate a design view into the PWA, but there is currently no release date yet.
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 Progressive Web App improves SEO by using Universal for pre-rendering complete pages. This way, the PWA is able to respond to web crawlers with fully 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 supports 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:
SSO configuration
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 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 to the fallback to the default language.
The basic idea for the PWA's language representation is having different domains for the different languages, e.g., www.example.com for English and www.example.de or de.example.com for the German version. With Multi-Site Handling (see Multi Channel Context Routing) this is 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 switch itself on login leads to issues especially if the login takes place on the checkout page. For this reason and for further considerations of the preferred language handling in language specific multi-site installations, this functionality is not completed yet.
An alternative idea for the PWA is setting the shop language based on the browser's language settings (see Set language based on browser setting).
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 PWA's 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 browser's 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.
Is It Possible to Use a Multi-Channel Approach for a Development Server?
A multi-channel approach is not supported for a development server as it would require the use of nginx. With the PWA and nginx running in a Docker container, the server would no longer be a development server, as changes are not automatically applied at runtime, but require a new Docker container build.
However, it is possible to run multiple development servers, each connected to different ports.
ng serve -c=b2c,development --port 4200 ng serve -c=b2b,development --port 4300
This way, multiple channels defined in the corresponding environment files are accessible through different ports at the same time. If this is not wanted, the channel in the environment.development.ts file must be changed whenever the channels are to be switched.
PWA Configuration
Please visit Configuration for further details.
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 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 have the express.js image log extended information to the console, supply the environment variable LOGGING=true. Please visit Logging for further details.
How to Deal With 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 Any 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.
What to Consider in Terms of 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.
Is It Possible to Share a Theme Across Multiple Environments on a Development Server?
Sharing a theme across environments on a development server is not possible by default because the environments currently do not specify the theme to be used. Instead, the suffix configuration specifies which theme the environment belongs to.
For example, the environment "environment.b2b.ts" is linked to the theme "b2b".
Please visit Multiple Themes for further details.
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.
Intershop CMS
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 a 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 built 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 Any Plans to Add Functionality to Delete a Customer via the intershop.REST Framework?
Since PWA version 7.10.20.x there is a new BACKOFFICE REST API that allows back office 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 will have been complete, the Angular storefront takes over again.
The main purpose of this approach is to enable the use of all PWA features while adding Responsive Starter Store 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 Responsive Starter Store 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 ICM 7.10 and 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 - Deployment of 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 Responsive Starter Store 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 an 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 built. 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 itself. 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
Please visit State Management for further details.
How Does the PWA Manage States?
Please visit State Management for further details on how the PWA manages its 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?
Due 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 provides means to dynamically configure the ICM channel and application to determine the correct REST endpoint for each incoming top level request.
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. Kubernetes is a portable extensible platform for managing containerized workloads and services that facilitates both declarative configuration and automation.
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.