This document describes how to run PWA and ICM in hybrid mode, so that pages from the Intershop Progressive Web App and pages from the classic storefront can be run in parallel.
A possible scenario would be to have the shopping experience with all its SEO optimizations handled by the PWA and to delegate highly customized parts of the checkout or my account area to the ICM.
For a minimal-invasive implementation, the mechanics for the hybrid approach are mainly implemented outside of the ICM and in deployment-specific components of the PWA.
The ICM is proxied in the express.js server of the server-side rendering process and hereby made available to the outside.
A newly introduced mapping table is also used to decide when an incoming request should be handled by the PWA or the ICM.
This mapping table is also used in the PWA for switching from the context of the single page application to the ICM.
The ICM must be run with Secure URL-only Server Configuration, which can be done by adding SecureAccessOnly=true
to the appserver configuration.
Furthermore the synchronization of the apiToken
cookie must be switched on, so that users and baskets are synchronized between PWA and ICM.
See Concept - Integration of Progressive Web App and inSPIRED Storefront.
If you also want to support the correct handling for links generated in e-mails, the property intershop.WebServerSecureURL
must point to nginx.
$SERVER/share/system/config/cluster/appserver.properties:
SecureAccessOnly=true
intershop.apitoken.cookie.enabled=true
intershop.apitoken.cookie.sslmode=true
intershop.WebServerSecureURL=https://<nginx>
The server-side rendering process must be started with SSR_HYBRID=1
.
In addition, the PWA must be run with secure URLs as well.
This can be achieved with SSL=1
.
⚠️ Only for development environments: It might be necessary to setTRUST_ICM=1
if the used development ICM is deployed with an insecure certificate.
Also, the Service Worker must be disabled for the PWA, as it installs itself into the browser of the client device and takes over the routing process, making it impossible to break out of the PWA and delegate to the ICM.
The mapping table resides in the PWA source code and provides the page-specific mapping configuration for the hybrid approach.
{
id: "Product Detail Page",
icm: `${ICM_CONFIG_MATCH}/ViewProduct-Start.*(\\?|&)SKU=(?<sku>[\\w-]+).*$`,
pwaBuild: `product/$<sku>${PWA_CONFIG_BUILD}`,
pwa: `^.*/product/([\\w-]+).*$`,
icmBuild: `ViewProduct-Start?SKU=$1`,
handledBy: "icm"
}
Each entry contains:
icm
and pwa
)pwaBuild
and icmBuild
)handledBy
(either icm
or pwa
) to decide on the target upstreamThe properties icm
and pwaBuild
can use named capture groups and are only used in the node.js process running on the server.
However, pwa
and icmBuild
are used in the client application where named capture groups are not yet supported by all browsers.
With version 0.23.0 the PWA was changed to no longer reuse the Responsive Starter Store application types but rather be based upon the newly introduced headless application type for REST Clients - intershop.REST
.
This application type is completely independent of the Responsive Starter Store and is not suitable for storefront setups using the hybrid approach.
For this reason, the PWA must be adapted to work with the Responsive Starter Store again.
Migration Steps to prepare the PWA for the hybrid approach with the Responsive Starter Store
commit | comment |
---|---|
50dc72ef0 | feat: switch to the new headless REST application type CMS content model (#302) |
741454c8c | feat: switch to the new headless REST application type applications demo content (#302) |
icmApplication
settingcomponentEntryPointDefinitions
in the ICM project source codeThe information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.