-
Notifications
You must be signed in to change notification settings - Fork 77
Frequently Asked Questions
Deployment Scenarios For Angular Applications
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.
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.
To get an overview of PWA migration, please visit Support Article - PWA Migration Guide.
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.
The system requirements for multiple different versions of the Intershop Progressive Web App can be found at Overview - Intershop Progressive Web App System Requirements.
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.
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.
Yes, any kind of contribution is appreciated. Please visit Guide - Intershop Progressive Web App - Contributing to the Intershop Progressive Web App for further details.
To get a detailed overview of the Intershop Progressive Web App structure, please visit Concept - Intershop Progressive Web App - Project Structure.
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.
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.
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.
Redirects are not part of the Intershop CaaS environments. Therefore, custom application code must generate the error pages and redirects.
There are plans to integrate a design view into the PWA, but there is currently no release date.
To get an overview of the CMS integration into the Intershop Progressive Web App, please visit Concept - Intershop Progressive Web App - CMS Integration.
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.
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.
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.
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).
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.
Please visit Configuration for further details.
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.
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.
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.
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.
This can be done using feature toggles such as guards, directives, pipes and services.
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.
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.
Please visit Localization for further details.
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.
Existing localization properties of the RSS can be converted to proper JSON files via a gradle plugin.
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.
Please visit Styling & Behavior for further details.
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.
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.
Please visit Testing the PWA for further details.
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.
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.
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.
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.
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.
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.
Please visit Concept - Headless Application Type - intershop.REST for further details.
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.
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.
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.
Please visit Hybrid Approach for further details.
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.
A mapping table is used to decide whether an incoming request should be handled by the PWA or by the ICM.
No, the headless application type is not suitable for storefront setups that use the hybrid approach.
Yes, it is possible to move available RSS functionality to the Angular storefront by migration.
Yes, there is a demo server for the PWA. Please visit Reference - Demo Server for Intershop PWA for further details.
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.
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.
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.
Please visit Deployment Scenarios for Angular Applications for further details.
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.
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.
It is possible to enable service workers by running node schematics/customization/service-worker true. Please visit Progressive Web App for further details.
Please visit State Management for further details on how the PWA manages it's states.
Yes, '@ngrx/entitiy' provides an API to manipulate and query entity collections.
Please visit Multi-Site Handling for further details.
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.
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.
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)
It is recommended to run three Kubernetes pods, each deploying a PWA instance, to ensure the reliability and also no downtimes during update processes.
The recommended way is to run one PWA in three Kubernetes pods. This approach is also scalable later on.
Currently, there is no solution for this and there are no plans to implement such a connector for newer versions of the PWA.
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.