Implementazioni headless in fasi

Ora sono possibili implementazioni in fasi di tecnologie headless per gli utenti di Storefront Reference Architecture (SFRA) e SiteGenesis. Ad esempio, è possibile implementare una nuova e accattivante esperienza delle pagine di prodotto con PWA Kit e mantenere il flusso di checkout su SFRA fino alla fase successiva della transizione headless. Questo approccio incrementale velocizza l'avvio delle implementazioni e riduce gli ostacoli verso la soluzione headless.

Questa guida descrive come utilizzare le regole di bridging e routing di sessione per consentire a PWA Kit di ottimizzare un set di pagine e a SFRA di ottimizzare un altro set di pagine con un'esperienza utente fluida.

Questa guida contiene le istruzioni per combinare i flussi PWA Kit e SFRA, che possono tuttavia essere adattate per SiteGenesis.

Per permettere agli acquirenti di navigare senza problemi tra pagine basate su architetture di storefront diverse è necessario utilizzare una tecnica denominata bridging di sessione. Il bridging di sessione utilizza i cookie per condividere i token di aggiornamento degli acquirenti e i token di sessione tra sistemi diversi.

Per usufruire del bridging di sessione è necessario utilizzare Shopper Login and API Access Service (SLAS), una nuova soluzione basata su standard per l'autenticazione e l'autorizzazione accessibile tramite richieste HTTP. L'autenticazione dell'acquirente con SLAS si basa su OpenID Connect, mentre l'autorizzazione per le Shopper API di Commerce Cloud si basa su OAuth 2.

Quando un acquirente naviga in uno storefront headless, si utilizza SLAS per richiedere un token di accesso e un token di aggiornamento e per memorizzarli come cookie nel browser dell'acquirente. È possibile impostare il cookie con l'intestazione set-cookie HTTP o con JavaScript di lato client. Quando l'acquirente passa da una pagina SFRA a una pagina PWA Kit (o viceversa), il cookie con il token di aggiornamento viene inviato insieme alla richiesta HTTP e il codice dello storefront può utilizzare il token di aggiornamento per l'accesso utente.

Impostazione di SLAS per PWA Kit

La prima operazione da eseguire per creare un'implementazione headless in fasi è impostare l'applicazione PWA Kit per l'uso di SLAS (se non lo si è già fatto). Seguire le istruzioni riportate nella guida Impostazione dell'accesso API.

Installazione del cartridge SLAS

Per consentire un'implementazione headless in fasi con SFRA, è necessario installare il cartridge plug-in SLAS. Le istruzioni di installazione complete sono riportate nel file README del cartridge.

Oltre al bridging di sessione, il cartridge plug-in SLAS consente di implementare altre funzionalità intuitive per l'acquirente, come sessioni utente di 90 giorni e permanenza del carrello.

Istruzioni per le implementazioni di SiteGenesis

Poiché il cartridge plug-in SLAS è progettato per SFRA, è necessario scrivere codice aggiuntivo per utilizzarlo con SiteGenesis. Un'implementazione di SiteGenesis può utilizzare il codice del cartridge in vari punti dei flussi di autenticazione e autorizzazione dell'acquirente.

Poiché il cartridge utilizza il framework di servizi web di B2C Commerce per gestire le chiamate API SLAS, un'implementazione di SiteGenesis può effettuare richieste ai servizi web implementati dal cartridge. Questi servizi web includono accesso utente ospite, accesso cliente registrato, aggiornamento token, disconnessione e unione del carrello utente. Il cartridge implementa anche un servizio per unire le sessioni API e le sessioni di storefront.

Un'implementazione di SiteGenesis può utilizzare anche un hook personalizzato (app.plugin.slas.login) per implementare l'accesso per gli utenti ospite e gli utenti registrati con SLAS. Esaminare il codice personalizzato nell'hook onSession del cartridge in dw.system.request.onSession per scoprire in che modo sostituisce Script API con SLAS per l'accesso acquirente.

Per consentire il bridging di sessione con PWA Kit, è necessario modificare il codice in commerce-api/auth.js che gestisce l'autorizzazione API per l'uso dei cookie al posto dell'archiviazione locale.

Se il progetto PWA Kit è stato generato con la versione 1.5.0 o successiva del modello Retail React App, è possibile rimuovere il commento da questa riga di codice in auth.js. Non sono richieste ulteriori modifiche al file.

Per i progetti generati prima della versione 1.5.0 è necessario apportare varie modifiche a commerce-api/auth.js. Per consentire un risparmio di tempo, è stata creata una versione alternativa del file contenente tutte le modifiche ed è stata resa disponibile su GitHub attraverso un gist pubblico.

Il flusso di autorizzazione inizia con il token di aggiornamento. Se il cookie del token di aggiornamento è disponibile, l'app PWA Kit scambia il token di aggiornamento con un token di accesso. In caso contrario, l'app inizia un flusso di concessione del codice di autorizzazione, come definito dallo standard OAuth 2. Inoltre, segue la chiave di prova per il flusso (PKCE) di scambio di codice.

Quando il nuovo token di accesso e il nuovo token di aggiornamento vengono concessi da SLAS, l'app li memorizza nei cookie, quindi effettua una richiesta POST all'endpoint di creazione sessione di OCAPI (/session). L'endpoint crea una sessione che viene utilizzata da SFRA. L'app memorizza il token di sessione in un cookie.

Cookie creati dall'app PWA Kit:

  • cc-nx-g - token di aggiornamento acquirente ospite SLAS
  • cc-nx - token di aggiornamento acquirente registrato SLAS
  • token - token di accesso SLAS
  • dwsid - ID sessione Demandware

Il diagramma seguente illustra il flusso di autorizzazione modificato per PWA Kit:

Associated diagram -large

Un altro aspetto importante di un'implementazione headless in fasi è il routing. Per gestire il traffico verso due sistemi diversi, è necessario impostare la CDN in modo da instradare il traffico verso due origini diverse: l'ambiente Managed Runtime e l'istanza B2C Commerce.

Si immagini lo scenario seguente:

Si dispone di uno storefront SFRA esistente in esecuzione su www.mystorefront.com. Si conoscono i vantaggi dell'architettura headless e si desidera sfruttare PWA Kit per offrire esperienze performanti e coinvolgenti. Allo stesso tempo, si desidera minimizzare i rischi di programmazione, quindi si mette a punto un piano per lanciare uno storefront PWA Kit adottando un approccio in fasi.

Il piano consiste nell'utilizzare PWA Kit per le pagine della parte superiore dell'imbuto: home page (/), pagina di elenco categorie (/category) e pagina dei dettagli di prodotto (/product). Queste pagine PWA Kit vengono distribuite in un ambiente Managed Runtime ospitato su mystorefront.mobify-storefront.com. Quando decide di effettuare un acquisto, l'acquirente viene reindirizzato alla pagina di checkout SFRA esistente ospitata su www.mystorefront.com.

Configurazione delle regole CDN

I clienti di una rete CDN incorporata (eCDN) devono contattare l'assistenza (Support) per configurare le regole di routing.

Ora è il momento di aggiungere un'origine all'area CDN per le pagine PWA Kit che punti all'ambiente Managed Runtime (mystorefront.mobify-storefront.com).

In seguito creare le regole di routing per gestire il traffico in base al percorso URL. Iniziare acquisendo un elenco completo di route per le pagine PWA Kit. Per un progetto PWA Kit basato sul modello Retail React App, le route sono elencate in app/routes.jsx. Poiché il sistema di rendering di lato server per PWA Kit utilizza route interne per i proxy e gli asset statici, è necessario includere anche /mobify/* nelle regole di routing.

Per lo scenario di esempio indicato è necessario configurare le seguenti route nella rete CDN:

Per ciascuna route PWA Kit dell'elenco, configurare la rete CDN in modo che inoltri la richiesta all'ambiente Managed Runtime (mystorefront.mobify-storefront.com nello scenario di esempio).

Il seguente diagramma mostra come configurare la rete CDN:

Associated diagram -medium

Installazione del cartridge di reindirizzamento (facoltativo)

Per impostazione predefinita, il modello Retail React App per i progetti PWA Kit ha uno schema di routing URL diverso rispetto a SFRA. Ad esempio, il percorso URL per una pagina dei dettagli di prodotto in Retail React App è /products/{productId}. Con SFRA, lo schema è /{categoryId}/{productId}.

Si consiglia di modificare gli schemi di routing nello storefront PWA Kit in base al sito SFRA. Se non si è in grado di abbinare gli schemi URL per una pagina specifica (come la pagina di elenco prodotti quando l'ID categoria non è disponibile nell'URL), è possibile utilizzare il cartridge di reindirizzamento per impostare i reindirizzamenti che colmano il divario. Le istruzioni di installazione complete sono riportate nel file README del cartridge.

Altre modifiche dei progetti PWA Kit

Per completare la procedura di impostazione per un'implementazione headless in fasi è necessario apportare alcune altre modifiche al progetto PWA Kit.

Per impostazione predefinita, PWA Kit utilizza History API per la navigazione. Quando un acquirente fa clic su un link creato con il componente <Link> di React Router, viene attivata una navigazione soft verso il componente corrispondente al percorso nell'oggetto route definito in app/routes.jsx. Per creare un link a una pagina non realizzata con PWA Kit (ad esempio basata su SFRA), è necessario rimuovere da app/routes.jsx qualsiasi route corrispondente al nome del percorso URL.

Ad esempio: rimuovere checkout dalla matrice di route. Remove-checkout-route

Infine, aggiornare la route generica PWA (/*) in app/routes.jsx. Sostituire il componente <PageNotFound /> PWA con un reindirizzamento all'origine predefinita.