Implementazioni headless in fasi

Ora sono possibili implementazioni in fasi di tecnologie headless per gli utenti di SFRA (Storefront Reference Architecture) 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.

Per creare un'esperienza utente senza interruzioni, utilizzare le regole di bridging e routing della sessione per consentire a PWA Kit di supportare un set di pagine e SFRA di supportarne un altro.

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

Di seguito è riportato un riepilogo dei passaggi chiave di un'implementazione headless in fasi.

1. Impostazione di SLAS per PWA Kit
2. Impostazione del bridging di sessione
3. Configurazione del Routing. Vedere anche CDN API per implementazioni headless in fasi.
4. Installazione del cartridge di reindirizzamento (facoltativo)
5. Esecuzione di altre modifiche ai progetti PWA Kit
6. Impostazione delle implementazioni in fasi in locale (facoltativo)
7. Recupero dati analitici tramite Einstein Activities per implementazioni headless in fasi (facoltativo)

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.

Quando si configura SLAS, è necessario decidere se configurare un client pubblico SLAS o un client privato SLAS, in quanto ciò influirà su alcuni dei passaggi di configurazione che seguono. Se si sta configurando un client privato SLAS, seguire la procedura descritta in Uso di un client privato SLAS per eseguire il setup.

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 effettua l'accesso
• quando il cookie di sessione di un acquirente è scaduto

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 ospiti non vengono trasferite all'utente registrato in fase di accesso.

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

La chiave per sbloccare il bridging di sessione è SLAS, una nuova soluzione basata su standard per l'autenticazione e l'autorizzazione a cui è possibile accedere 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. Quando l'acquirente passa da una pagina SFRA a una pagina PWA Kit (o viceversa), i cookie con il token di accesso e il token di aggiornamento vengono inviati insieme alla richiesta HTTP e PWA Kit/SFRA li utilizzano per ereditare la stessa sessione.

Per ulteriori informazioni ed esempi di bridging di sessione, vedere Panoramica sul bridging di sessione.

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 della sessione, quindi lo storefront non richiede un nuovo rendering e può ricevere una risposta 200 OK.
2. Bridge di sessione OCAPI (Open Commerce API) (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.

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 SLAS concede il nuovo token di accesso e il nuovo token di aggiornamento, l'app li archivia 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, utilizzare una rete CDN per instradare il traffico a due origini diverse: l'ambiente MRT (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 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 ulteriori informazioni sul routing del traffico a MRT, vedere:

• API CDN per implementazioni headless in fasi
• Certificati TLS
• CNAME DNS
• Configurazione dell'ambiente

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 (On-Demand Sandbox).
• 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 riesce a riprodurre i formati URL di una pagina specifica (ad esempio la pagina dell'elenco dei prodotti quando l'ID categoria non è disponibile nell'URL), utilizzare il cartridge di reindirizzamento per impostare i reindirizzamenti richiesti. 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 PWA <PageNotFound /> 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 SiteGenesis) e MRT. Tuttavia, la rete eCDN non supporta i gruppi di istanze secondarie (SIG) e le istanze ODS. Per impostare e testare localmente i siti con implementazioni in fasi sulle 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.

Questo video dimostrativo mostra i passaggi per configurare le implementazioni in fasi nelle istanze SIG.

Phased Rollouts on SIG

È possibile configurare la propria istanza ODS affinché utilizzi la configurazione di un alias simile alla configurazione di produzione. In questo modo è possibile 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.

La chiamata al bridge di sessione OCAPI dopo l'accesso acquirente sulle pagine PWA Kit è necessaria per inviare una notifica alle pagine SFRA ogni volta che lo stato di autenticazione dell'acquirente cambia sulle pagine PWA Kit. Ogni volta che lo stato di autenticazione dell'acquirente cambia, PWA Kit invia la nuova chiamata di access_token in /sessions per il bridging della sessione e riceve un nuovo file dwsid. Il valore del cookie dwsid viene aggiornato con quello ricevuto nella risposta /sessions.

PWA Kit v3.4.0 e versioni precedenti PWA Kit conserva una copia del token di aggiornamento in LocalStorage che viene confrontata con la chiave e il valore del token di aggiornamento memorizzati in CookieStorage prima di ogni richiesta. Se i token differiscono, PWA Kit invalida la sessione corrente e attiva nuovamente il flusso di autorizzazione per mantenere le sessioni sincronizzate con SFRA.

Modifiche a PWA Kit v3.5.0 (commerce-sdk-react@1.4.0)
È stata aggiornata la logica utilizzata per invalidare le sessioni di PWA Kit in base allo stato di autenticazione dell'acquirente in SFRA in un'impostazione di lancio in fasi. SFRA ora memorizza l'access_token SLAS in un cookie con chiave access_token_sfra. Quando un acquirente passa da SFRA a PWA Kit, questo cookie viene condiviso con PWA Kit. Il cookie può contenere il valore access_token effettivo proveniente da SLAS se è disponibile un token di accesso valido. In caso contrario, il valore del cookie viene impostato su refresh. Se appare un access_token valido, PWA Kit sostituisce il valore corrente di access_token con il valore del cookie access_token_sfra. Se access_token_sfra è impostato su refresh, PWA Kit attiva il flusso di accesso del token di aggiornamento per ottenere un nuovo access_token.

Per i dettagli sull'implementazione, vedere getAccessToken() .

B2C Commerce analizza il flusso di clic della sessione associata a dwsid. Un flusso di clic vuoto indica una nuova sessione e comporta l'attivazione di onSession. Un valore nuovo o modificato del cookie dwsid non implica direttamente che la sessione sia nuova.

In un'impostazione di lancio in fasi, PWA Kit richiama l'endpoint OCAPI /sessions per il bridging delle sessioni B2C Commerce e SLAS ogni volta che lo stato di accesso dell'acquirente cambia per notificare a SFRA il cambiamento dello stato di accesso. L'endpoint /sessions restituisce un nuovo valore per dwsid che è associato alla sessione di bridging e che quindi ha un flusso di clic vuoto. Così viene attivato onSession quando un acquirente accede al sito SFRA.

Se un acquirente passa ripetutamente da un sito PWA Kit a un sito SFRA o viceversa, è possibile che il valore dwsid cambi, ma potrebbe comunque rimanere associato a una sessione B2C Commerce in corso o avere un flusso di clic non vuoto. In tale situazione, l'hook onSession non viene attivato.

• CDN API per implementazioni headless in fasi
• Einstein Activities per implementazioni headless in fasi
• Guida introduttiva a Composable Storefront