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.

Per ulteriori informazioni sull'utilizzo di Einstein Activities in un contesto headless in fasi, consultare Einstein Activities per implementazioni headless in fasi.

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.

Il cartridge plug-in SLAS gestisce le sessioni di B2C Commerce (associate a un dwsid) nonché le sessioni SLAS (associate a un access_token). Il bridging di sessione collega dwsid e access_token alla stessa sessione acquirente.

Il cartridge plug-in SLAS utilizza 2 metodi di bridging di sessione:

1. Bridge di sessione SLAS (API: getSessionBridgeAccessToken)
   • Utilizzato dal cartridge plug-in SLAS solo per il nuovo accesso utente ospite.
   • Non genera un nuovo dwsid dopo il bridging di sessione. Lo storefront quindi non richiede un nuovo rendering e può ricevere una risposta 200 OK.
2. Bridge di sessione OCAPI (API: Obtain OCAPI Session)
   • Utilizzato dal cartridge plug-in SLAS per l'accesso acquirente registrato e l'accesso al token di aggiornamento.
   • Genera un nuovo dwsid dopo il bridging di sessione. Lo storefront quindi richiede un aggiornamento e deve ricevere una risposta Reindirizzamento 302.

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.

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.

Importanti considerazioni per gli utenti del cartridge SLAS

Il cartridge plug-in SLAS effettua più chiamate a varie API, il che può influire sulle prestazioni dello storefront. Prima di aggiungere il cartridge a uno storefront Production, confrontare le prestazioni dello storefront con e senza il cartridge per decidere se è adatto alle proprie esigenze.

Il cartridge introduce inoltre un reindirizzamento nei seguenti casi:

• quando un acquirente non ha ancora un cookie di sessione
• quando il cookie di sessione di un acquirente è scaduto
• quando un motore di ricerca sta indicizzando il sito

Attualmente il cartridge sostituisce solo l'accesso diretto al sistema B2C Commerce le cui credenziali sono archiviate in Salesforce.

Se utilizzato con il plug-in delle liste desideri, le liste desideri degli ospiti non vengono trasferite al momento dell'accesso all'utente registrato.

Prima di utilizzare il cartridge, consultare la pagina dei problemi su GitHub.

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 2.7.x del modello Retail React App, è possibile rimuovere il commento da questa riga di codice in auth.js per passare a CookieStorage per l'archiviazione dei token. Questa operazione è necessaria per la gestione delle sessioni tra i siti SFRA e PWA Kit.

È necessario inoltre modificare il codice in commerce-api/auth.js che richiama l'API del bridge di sessione dopo l'accesso acquirente. A questo scopo, rimuovere il commento da questa riga di codice in 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.

Se il progetto PWA Kit è stato generato con la versione 3.0.0 o successiva del modello Retail React App, le modifiche sopra citate sono abilitate per impostazione predefinita e non sono richieste ulteriori modifiche al codice.

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.1. 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

Per garantire un'esperienza utente ottimale durante un'implementazione in fasi, è necessario un modo per instradare il traffico verso due origini diverse: l'ambiente Managed Runtime e l'istanza B2C Commerce. L'instradamento del traffico può essere gestito da una CDN (Content Delivery Network/rete per la distribuzione di contenuti).

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 sceglie un approccio in fasi per implementare uno storefront PWA Kit.

Si configura la rete CDN in modo che invii le richieste di pagina nella parte superiore dell'imbuto a PWA Kit: home page (/), pagina di elenco categorie (/category) e pagina di dettagli 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 dalla rete CDN alla pagina di checkout SFRA esistente ospitata su www.mystorefront.com.

Per gestire l'instradamento del traffico, è possibile scegliere la soluzione eCDN (CDN incorporata) di Salesforce (con tecnologia Cloudflare) oppure una rete CDN di un altro provider.

Per utilizzare la eCDN per instradare il traffico a Managed Runtime, usare l'endpoint Commerce API createMrtRules.

L'API supporta l'instradamento del traffico a Managed Runtime mediante le espressioni regola di Cloudflare. Supporta un sottoinsieme dei campi disponibili nel linguaggio delle regole. Sono supportati i seguenti campi:

• http.host da abbinare al nome host
• http.request.uri.path da abbinare al percorso della richiesta
• http.request.uri da abbinare sia al percorso della richiesta sia alla stringa di query
• http.cookie da abbinare ai cookie

È possibile richiedere 100 regole singole per istanza nelle zone proxy e 100 regole singole in totale condivise tra istanze Development/Production nelle zone legacy.

• L'eCDN è disponibile solo per le istanze Production e Development, ma non per le istanze Sandbox o ODS.
• L'onboarding nella rete eCDN delle istanze Staging deve avvenire mediante l'API eCDN. Per ulteriori informazioni, consultare Configurazione della rete eCDN per le istanze Staging nell'Infocenter di B2C Commerce e questo articolo del blog Rhino Inquisitor.
• La rete eCDN non supporta l'instradamento basato sulla geolocalizzazione.

Per progettare le regole di origine, acquisire 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:

Creare una regola di origine che includa tutte le route PWA Kit dell'elenco per inoltrare la richiesta all'ambiente Managed Runtime (mystorefront.mobify-storefront.com nello scenario di esempio).

Il diagramma seguente illustra la configurazione eCDN per lo scenario di esempio descritto in precedenza:

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.

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, se il progetto PWA Kit è stato generato con la versione 2.7.x o la versione 3.x del modello Retail React App senza utilizzare l'estensibilità, rimuovere il checkout dalla matrice di route.

Se il progetto PWA Kit è stato generato con la versione 3.x del modello Retail React App utilizzando l'estensibilità, è possibile eseguire l'override del file overrides/app/routes.jsx per filtrare i link alle pagine non realizzate con PWA Kit utilizzando JavaScript. È stato creato un override di esempio del file overrides/app/routes.jsx contenente tutte le modifiche per escludere le route /cart e /checkout ed è stato reso disponibile su GitHub tramite un gist pubblico.

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

Per le istanze PIG i clienti possono utilizzare la rete eCDN per "suddividere" il traffico tra le origini SFRA (o SG) e MRT. Tuttavia, la rete eCDN non supporta le istanze SIG e ODS. Per impostare e testare localmente i siti con implementazioni in fasi nelle istanze SIG, i clienti devono utilizzare il proprio proxy inverso o la rete CDN per suddividere il traffico.

È stata creata un'app Node.js di esempio che può essere utilizzata per sviluppare e testare i flussi di acquirenti con distribuzione ibrida su PWA Kit e SFRA/SiteGenesis. Le istruzioni di impostazione e configurazione del proxy inverso sono menzionate nel file README per il repository.

È stato realizzato un video dimostrativo che illustra la procedura per impostare le implementazioni in fasi nelle istanze SIG:

È possibile configurare l'ODS per l'utilizzo di una configurazione di alias simile a quella dell'ambiente Production per mantenere identiche le impostazioni locali e di produzione. Ad esempio, se si configura la Sandbox in modo che il sito ibrido sia disponibile all'URI /, gli URL inviati da pwa-kit includeranno l'ID di sito senza dover essere tradotti. Questa è la configurazione tipica di un sito Production.

Per abilitare gli alias in Business Manager, seguire le istruzioni in questo modulo per Salesforce B2C Commerce Hostname Aliases in Trailhead.

È possibile configurare le route PWA Kit in modo da includere il prefisso /s/SiteID a tutti gli URL in uscita (ad esempio quelli destinati a SFRA). In questo modo, l'istanza riceverà gli URL del controller secondo la modalità normalmente utilizzata nelle Sandbox senza che sia necessario configurare esplicitamente gli alias dei nomi host. Questa configurazione potrebbe non essere appropriata per gli ambienti Production. Pertanto, è consigliabile prevedere una route generica diversa a seconda che la distribuzione sia Production o Sandbox.

Per configurare i prefissi route, aggiornare la route generica PWA (/*) in app/routes.jsx o overrides/app/routes.jsx.