Phasenweise Headless-Rollouts

Phasenweise Rollouts von Headless-Technologien sind nun für Benutzer von Storefront Reference Architecture (SFRA) und SiteGenesis möglich. Sie können beispielsweise ein gewagtes neues Erlebnis für Produktseiten mit dem PWA Kit bereitstellen und den Checkout bis zur nächsten Phase Ihres Wechsels zu Headless weiterhin über SFRA abwickeln. Dieser phasenweise Ansatz hilft Ihnen dabei, früher zu beginnen, und minimiert Unterbrechungen auf Ihrem Weg zu Headless.

In dieser Anleitung wird beschrieben, wie Sie Session Bridging und Routing-Regeln verwenden, damit zwischen mit PWA Kit und mit SFRA betriebenen Seiten eine nahtlose Benutzererfahrung möglich ist.

Unter Einstein Activities für das phasenweise Headless-Rollout können Sie mehr über die Verwendung von Einstein Activities im Kontext eines phasenweisen Headless-Rollouts erfahren.

Damit Käufer nahtlos zwischen Seiten mit unterschiedlicher Storefront-Architektur navigieren können, ist ein Vorgang mit der Bezeichnung Session Bridging erforderlich. Beim Session Bridging werden Cookies verwendet, um die Aktualisierungstoken und Sessiontoken von Käufern in unterschiedlichen Systemen zu teilen.

Session Bridging funktioniert mithilfe des Shopper Login and API Access Service (SLAS). Dabei handelt es sich um eine neue standardbasierte Lösung für die Authentifizierung und Autorisierung, auf die über HTTP-Anfragen zugegriffen werden kann. Die Käuferauthentifizierung mit SLAS basiert auf OpenID Connect und die Autorisierung für die Shopper-APIs von Commerce Cloud basiert auf OAuth 2.

Wenn ein Käufer eine Headless-Storefront besucht, verwenden Sie SLAS, damit ein Zugriffstoken und ein Aktualisierungstoken angefordert und als Cookies im Browser des Käufers gespeichert werden. Sie können den Cookie mit dem HTTP-Header set-cookie oder auf der Clientseite mit JavaScript festlegen. Wenn ein Käufer von einer SFRA-Seite auf eine PWA Kit-Seite wechselt (oder umgekehrt), wird der Cookie mit dem Aktualisierungstoken zusammen mit der HTTP-Anfrage gesendet. Der Storefront-Code kann den Benutzer dann mithilfe des Aktualisierungstokens anmelden.

Plugin SLAS verwaltet sowohl B2C Commerce Sessions (verknüpft mit einer dwsid) als auch SLAS-Sessions (verknüpft mit einem access_token). Session Bridging verbindet dwsid und access_token mit derselben Käufer-Session.

Plugin SLAS verwendet beim Session Bridging zwei Methoden:

1. SLAS Session Bridge (API: getSessionBridgeAccessToken)
   • Diese Methode wird von Plugin SLAS nur für neue Gast-Anmeldungen verwendet.
   • Nach dem Session Bridging wird keine neue dwsid generiert, d. h. die Storefront muss nicht erneut gerendert werden und eine 200 OK-Antwort kann gesendet werden.
2. OCAPI Session Bridge (API: Obtain OCAPI Session)
   • Diese Methode wird von Plugin SLAS für die Anmeldung registrierter Käufer und die Aktualisierungstoken-Anmeldung verwendet.
   • Da nach dem Session Bridging eine neue dwsid generiert wird, muss die Storefront aktualisiert werden und eine 302 Redirect-Antwort an die Storefront gesendet werden.

Der erste Schritt für einen phasenweisen Headless-Rollout ist, Ihre PWA Kit-Anwendung für die Verwendung von SLAS einzurichten (falls Sie dies noch nicht getan haben). Befolgen Sie die Anweisungen in der Anleitung Einrichtung des API-Zugriffs.

Damit ein phasenweiser Headless-Rollout mit SFRA möglich ist, müssen Sie die Plugin SLAS Cartridge installieren. Die vollständige Installationsanleitung finden Sie in der README-Datei der Cartridge.

Wichtige Überlegungen für Benutzer von SLAS Cartridges

Die Plugin SLAS Cartridge macht mehrere Aufrufe an verschiedene APIs, was die Storefront-Leistung beeinträchtigen kann. Bevor Sie die Cartridge zu einer Production-Storefront hinzufügen, vergleichen Sie die Leistung Ihrer Storefront mit und ohne Cartridge, um zu entscheiden, ob diese Cartridge für Sie geeignet ist.

Die Cartridge löst darüber hinaus unter den folgenden Bedingungen eine Umleitung aus:

• Wenn ein Käufer noch kein Session-Cookie hat
• Wenn das Session-Cookie eines Käufer abgelaufen ist
• Wenn eine Suchmaschine gerade Ihre Website indexiert

Derzeit ersetzt die Cartridge nur dort die Direktanmeldung im B2C Commerce-System, wo die Anmeldedaten innerhalb von Salesforce gespeichert sind.

Bei Verwendung mit dem Wishlists Plugin werden die Wunschlisten von Gästen bei der Anmeldung nicht auf den registrierten Benutzer übertragen.

Lesen Sie vor Verwendung der Cartridge die Seite mit bekannten Problemen auf GitHub.

Da die Plugin SLAS Cartridge für SFRA ausgelegt ist, muss für die Verwendung mit SiteGenesis zusätzlicher Code geschrieben werden. Eine SiteGenesis-Implementierung kann an verschiedenen Punkten der Flows zur Käuferauthentifizierung und -autorisierung Code von der Cartridge nutzen.

Da die Cartridge das B2C Commerce Web Service Framework für die Bearbeitung von SLAS API-Aufrufe verwendet, kann eine SiteGenesis-Implementierung Anfragen an die von der Cartridge implementierten Web-Services stellen. Zu diesen Web-Services gehören die Gastanmeldung, die Anmeldung von registrierten Kunden, die Aktualisierung von Token, die Abmeldung und das Zusammenführen des Gastwarenkorbs. Die Cartridge implementiert auch einen Service zum Zusammenführen von API-Sessions und Storefront-Sessions.

Eine SiteGenesis-Implementierung kann ebenfalls einen benutzerdefinierten Hook (app.plugin.slas.login) nutzen, um die Anmeldung für Gäste und registrierte Benutzer mit SLAS zu implementieren. Sehen Sie sich den benutzerdefinierten Code im onSession-Hook der Cartridge in dw.system.request.onSession an, um zu sehen, wie die Script API für die Käuferanmeldung mit SLAS ersetzt wird.

Damit Session Bridging mit dem PWA Kit möglich ist, müssen Sie den Code für die API-Autorisierung in commerce-api/auth.js bearbeiten, damit Cookies anstelle des lokalen Speichers verwendet werden.

Wurde Ihr PWA Kit-Projekt mit Version 2.7.x der Retail React App-Vorlage erstellt, können Sie die Kommentarmarkierung dieser Codezeile in auth.js aufheben, um anschließend CookieStorage für die Speicherung von Token zu nutzen. Dies ist für die Verwaltung von Sessions zwischen SFRA- und PWA Kit-Websites erforderlich.

Sie müssen ebenfalls den Code in commerce-api/auth.js ändern, der die Session-Bridge API nach der Käuferanmeldung aufruft. Heben Sie dazu die Kommentarmarkierung dieser Codezeile in auth.js auf.

Um Ihnen Zeit zu sparen, haben wir eine alternative Version der Datei mit allen Änderungen erstellt und bei GitHub als öffentlichen Gist zur Verfügung gestellt.

Wurde Ihr PWA Kit-Projekt mit Version 3.0.0 oder einer neueren Version der Retail React App-Vorlage erstellt, sind die oben aufgeführten Änderungen standardmäßig aktiviert und es sind keine weiteren Codeänderungen erforderlich.

Der Autorisierungs-Flow beginnt mit dem Aktualisierungstoken. Wenn ein Cookie für den Aktualisierungstoken verfügbar ist, tauscht die PWA Kit App den Aktualisierungstoken gegen einen Zugriffstoken aus. Ansonsten startet die App einen Flow zur Gewährung eines Autorisierungscodes wie vom OAuth 2.1-Standard definiert. Sie folgt außerdem dem Flow Proof Key for Code Exchange (PKCE).

Wenn die neuen Zugriffs- und Aktualisierungstoken von SLAS gewährt werden, speichert die App sie in Cookies. Dann führt die App eine POST-Anfrage an OCAPI zum Erstellen eines Session-Endpunkts (/session) aus. Dieser Endpunkt erstellt eine Session, die von SFRA verwendet wird. Die App speichert das Sessiontoken in einem Cookie.

Von der PWA Kit App erstellte Cookies:

• cc-nx-g – SLAS Aktualisierungstoken für Gastkäufer
• cc-nx – SLAS Aktualisierungstoken für registrierten Käufer
• token – SLAS Zugriffstoken
• dwsid – Demandware Session-ID

Um während eines phasenweisen Rollouts eine problemlose Benutzererfahrung zu gewährleisten, benötigen Sie eine Möglichkeit, den Traffic an zwei verschiedene Ursprünge zu leiten: an die Managed Runtime-Umgebung und an Ihre B2C Commerce-Instanz. Dieses Traffic-Routing kann von einem Content Delivery Network (CDN) gehandhabt werden.

Stellen Sie sich das folgende Szenario vor:

Sie haben eine bestehende SFRA-Storefront unter www.mystorefront.com. Sie kennen die Vorteile der Headless-Architektur und möchten PWA Kit nutzen, um leistungsstarke und attraktive Erlebnisse zu schaffen. Da Sie gleichzeitig Risiken bei der Zeitplanung minimieren möchten, entscheiden Sie sich bei der Einführung Ihrer PWA Kit-Storefront für einen phasenweisen Ansatz.

Sie konfigurieren das CDN so, dass es oben im Trichter eine Seitenanforderung an PWA Kit senden: Startseite (/), Kategorieseite (/category) und Produktdetailseite (/product). Die PWA Kit-Seiten werden auf einer Managed Runtime-Umgebung unter mystorefront.mobify-storefront.com bereitgestellt. Wenn sich ein Käufer zum Kauf entschließt, leitet ihn das CDN auf die bestehende SFRA-Seite für die Kaufabwicklung unter www.mystorefront.com weiter.

Beim Traffic-Routing können Sie sich für die eingebettete CDN-Lösung (eCDN) von Salesforce (unterstützt von Cloudflare) oder für ein CDN eines anderen Anbieters entscheiden.

Verwenden Sie für das Traffic-Routing an Managed Runtime über eCDN den Commerce API-Endpunkt createMrtRules.

Die API unterstützt mithilfe von Cloudflare Rule Expressions das Traffic-Routing an Managed Runtime. Sie unterstützt in der Regelsprache eine Teilmenge der verfügbaren Felder. Die folgenden Felder werden unterstützt:

• http.host für den Abgleich mit dem Host-Namen
• http.request.uri.path für den Abgleich mit dem Anfragepfad
• http.request.uri für den Abgleich mit sowohl dem Anfragepfad als auch dem Abfrage-String
• http.cookie für den Abgleich von Cookies

In Proxy-Zonen können Sie pro Instanz 100 individuelle Regeln und in veralteten Zonen insgesamt 100 individuelle Regeln für die gemeinsame Nutzung durch DEV/PROD-Instanzen anfordern.

• Das eCDN ist nur für PROD- und DEV-Instanzen verfügbar, aber nicht für Sandbox- oder ODS-Instanzen.
• Für Staging-Instanzen muss mithilfe der eCDN API ein Onboarding in das eCDN durchgeführt werden. Näheres dazu finden Sie im B2C Commerce Infocenter unter Configure eCDN for Staging (Konfiguration von eCDN für Staging-Instanzen) und in diesem Artikel im Blog "Rhino Inquisitor".
• Das eCDN unterstützt kein Geolocation-Routing.

Stellen Sie eine umfassende Liste von Routen für PWA Kit-Seiten zusammen; diese Liste wird Ihnen beim Entwurf Ihrer Ursprungsregeln helfen. Für ein PWA Kit-Projekt auf Grundlage der Retail React App-Vorlage sind die Routen in app/routes.jsx aufgelistet. Da das serverseitige Rendering-System für PWA Kit interne Routen für Proxies und statische Assets verwendet, müssen Sie /mobify/* ebenfalls in die Routing-Regeln einbeziehen.

Für unser Beispielszenario müssen die folgenden Routen in Ihrem CDN konfiguriert werden:

Erstellen Sie eine Ursprungsregel, die alle PWA Kit-Routen auf Ihrer Liste enthält, um die Anfrage an die Managed Runtime-Umgebung (in unserem Beispielszenario mystorefront.mobify-storefront.com) weiterzuleiten.

Das folgende Diagramm zeigt die eCDN-Konfiguration für das zuvor beschriebene Beispielszenario:

Standardmäßig hat die Retail React App-Vorlage für PWA Kit-Projekte ein anderes Muster für das URL-Routing als SFRA. So lautet der URL-Pfad für eine Produktdetailseite in der Retail React App beispielsweise /products/{productId}. Bei SFRA ist das Muster /{categoryId}/{productId}.

Wir empfehlen Ihnen, die Routing-Muster in Ihrer PWA Kit-Storefront so zu ändern, dass diese Ihrer SFRA-Website entsprechen. Können Sie die URL-Muster für eine bestimme Seite nicht entsprechend anpassen (beispielsweise für die Produktlistenseite, wenn die Kategorie-ID nicht in der URL verfügbar ist), dann können Sie die Redirect Cartridge verwenden, um mithilfe von Umleitungen die Lücke zu schließen. Die vollständige Installationsanleitung finden Sie in der README-Datei der Cartridge.

Um den Einrichtungsprozess für einen phasenweisen Headless-Rollout abzuschließen, müssen Sie noch einige weitere Änderungen an Ihrem PWA Kit-Projekt vornehmen.

Standardmäßig verwendet PWA Kit die History API für die Navigation. Klickt ein Käufer auf einen mit der <Link>-Komponente von React Router erstellten Link, wird eine softe Navigation zu der Komponente ausgelöst, die dem Pfad des in app/routes.jsx definierten Routenobjekts entspricht. Zum Verlinken einer nicht mit PWA Kit betriebenen Seite (beispielsweise einer SFRA-Seite) müssen Sie jede dem URL-Pfadname entsprechende Route aus app/routes.jsx entfernen.

Wurde Ihr PWA Kit-Projekt zum Beispiel mit Version 2.7.x oder Version 3.x der Retail React App-Vorlage ohne Verwendung der Erweiterbarkeit generiert, entfernen Sie die Kaufabwicklung aus dem Routen-Array.

Wurde Ihr PWA Kit-Projekt mit Version 3.x der Retail React App-Vorlage mit Verwendung der Erweiterbarkeit generiert, können Sie die Datei overrides/app/routes.jsx überschreiben, um Links mithilfe von JavaScript aus Nicht-PWA Kit-Seiten herauszufiltern. Wir haben eine Beispiel-Überschreibung der Datei overrides/app/routes.jsx erstellt, die bereits alle erforderlichen Änderungen für das Herausfiltern von /cart- und /checkout-Routen enthält. Auf diese Überschreibung können Sie über einen öffentlichen Gist von GitHub zugreifen.

Aktualisieren Sie zum Schluss die PWA Catch-all-Route (/*) in app/routes.jsx. Ersetzen Sie die PWA-Komponente '' mit einer Umleitung an den Standardursprung.

Bei PIG-Instanzen können Kunden mithilfe von eCDN den Traffic zwischen SFRA (oder SG)- und MRT-Ursprüngen "splitten". SIG-Instanzen und ODS werden jedoch nicht von eCDN unterstützt. Um Websites mit phasenweisem Rollout lokal auf SIG-Instanzen einzurichten und zu testen, müssen Kunden ihren eigenen Reverse Proxy oder ihre eigenes CDN für die Traffic-Aufteilung verwenden.

Wir haben eine Beispiel-Node.js-App erstellt, mit der Sie Käufer-Flows mit hybrider Bereitstellung über PWA Kit und SFRA/SiteGenesis entwickeln und testen können. Anweisungen für die Einrichtung und Konfiguration eines Reverse Proxys werden in der INFO-Datei des Repos erwähnt.

Wir haben ein Demovideo mit den Schritten zur Einrichtung von phasenweisen Rollouts auf SIG-Instanzen zusammengestellt:

Sie können Ihre ODS so konfigurieren, dass sie eine Ihrer Produktionskonfiguration ähnliche Aliaskonfiguration verwendet. Auf diese Weise bleibt das Setup von lokalen und Production-Instanzen identisch. Indem Sie beispielsweise Ihre Sandbox so konfigurieren, dass Ihre hybride Website unter der /-URI verfügbar ist, stellen Sie sicher, dass die von pwa-kit gesendeten URLs nicht übersetzt werden müssen, damit sie die Website-ID enthalten. Dies entspricht der üblichen Konfiguration einer Production-Website.

Wenn Sie Aliasse im Business Manager aktiveren möchten, befolgen Sie die Anweisungen in diesem Trailhead-Modul für Salesforce B2C Commerce Host-Namen-Aliasse.

Sie können Ihre PWA Kit-Routenkonfiguration so konfigurieren, dass alle ausgehenden URLs (wie z. B. die für SFRA bestimmten) das Präfix /s/SiteID enthalten. Dies gewährleistet, dass Ihre Instanz Controller-URLs auf eine Weise erhält, die normalerweise für Sandboxes verwendet wird, ohne dass Sie Host-Namen-Aliasse erst ausdrücklich konfigurieren müssen. Hinweis: Dies ist möglicherweise nicht für die Production-Konfiguration geeignet. Deshalb empfiehlt sich eine andere Catch-All-Route für Production-Bereitstellungen als für Sandbox-Bereitstellungen.

Aktualisieren Sie zur Konfiguration der Routenpräfixe die PWA-Catch-All-Route (/*) in app/routes.jsx oder overrides/app/routes.jsx.