Storefront Preview

È possibile utilizzare Storefront Preview (Anteprima storefront) per vedere come apparirà il sito PWA (Progressive Web App) Kit in base a un contesto specifico, ad esempio il codice sorgente specificato, i gruppi di clienti o una data o un'ora particolari. Ad esempio, questa funzionalità si può usare se si desidera visualizzare in anteprima come apparirà il proprio sito in occasione di una vendita imminente.

Sono in arrivo i saldi del Black Friday/Cyber Monday? È possibile visualizzare in anteprima le modifiche al sito in ambiente Staging. Quindi, prima di distribuire le modifiche all'ambiente Production, assicurarsi che quelle apportate a elementi quali prodotti, prezzi e strategie di marketing funzionino nel modo previsto.

Inoltre, è possibile integrare Storefront Preview con un sistema CMS (Content Management System) di terze parti. Supponiamo, ad esempio, che si abbia un banner di vendite natalizie gestito dal tuo CMS. È possibile consentire al CMS di riconoscere il contesto corrente, ad esempio la data e l'ora effettive, in modo che l'anteprima del sito visualizzi il contenuto corretto, ad esempio il banner dei saldi natalizi per il periodo specificato.

Storefront Preview è disponibile in Runtime Admin. Questa guida spiega come configurare, utilizzare e risolvere i problemi di Storefront Preview.

Per utilizzare Storefront Preview, è necessario innanzitutto:

Creare il proprio sito utilizzando PWA Kit versione 2.8.3 o successiva, oppure 3.2.x con @salesforce/commerce-sdk-react@1.4.0 o @salesforce/retail-react-app@2.4.0. Storefront Preview non è disponibile nelle versioni di PWA Kit precedenti alla 2.8.3 o alla 3.2.x. Eseguire l'upgrade del progetto affinché utilizzi PWA Kit 2.8.3 o 3.2.x a seconda della versione principale corrente.
Avere accesso al progetto in Runtime Admin in qualsiasi ruolo diverso da Sola lettura. Se non si dispone dell'accesso, chiedere assistenza a qualcuno con ruolo di amministratore di Managed Runtime (MRT).
Abilitare il contesto acquirente in Business Manager.
Configurare il sito in base alla funzionalità che si desidera convalidare in Storefront Preview. Esempi:
- Impostare qualificatori personalizzati e ID di gruppo clienti utilizzando i gruppi clienti in Business Manager per applicare regole a prezzi, promozioni o prodotti personalizzati.
- Per visualizzare un'esperienza di acquisto personalizzata, impostare il codice sorgente che richiama gli endpoint Shopper Context. Questa operazione è necessaria perché Storefront Preview utilizza i dati contestuali per la personalizzazione.
- Impostare il prezzo che si desidera offrire in una data specifica. In questo modo il prezzo specificato viene visualizzato quando si seleziona tale data in Storefront Preview.
Seguire la procedura di configurazione descritta nella sezione Configurazione di Storefront Preview.
Configurare il browser in modo da consentire l'utilizzo dei cookie di terze parti su https://runtime.commercecloud.com.

Facoltativamente è possibile scrivere una funzione se si desidera integrare Storefront Preview con un CMS di terze parti. Vedere Aggiunta del componente StorefrontPreview al proprio storefront e Integrazione con un CMS di terze parti.

La funzione da scrivere per l'integrazione con un CMS di terze parti deve essere asincrona. In questo modo si eviteranno risultati imprevisti durante l'anteprima del sito.

È possibile utilizzare Storefront Preview con le versioni più recenti di Chrome o Safari. Il proprio browser deve consentire a https://runtime.commercecloud.com l'accesso ai cookie di terze parti. Storefront Preview non funzionerà se non si abilitano i cookie di terze parti.

Come abilitare i cookie di terze parti per Chrome e Safari.

I dati e le esperienze visualizzati in Storefront Preview non riflettono necessariamente l'esperienza dell'acquirente. La personalizzazione dell'acquirente richiede l'utilizzo della Shopper Context API all'interno del proprio progetto PWA Kit. Ulteriori informazioni su Shopper Context.
Storefront Preview mostra le pagine dello storefront così come appaiono a un utente ospite sul sito. Un utente ospite può ad esempio visualizzare contenuti di prodotto o marketing, prezzi, promozioni, elenchi di prodotti o pagine di visualizzazione dei prodotti. Non verranno visualizzati i contenuti visibili a un utente che ha eseguito l'accesso, ad esempio le informazioni relative all'account o al carrello.
Storefront Preview funziona sulle pagine di PWA Kit e non sulle pagine di Storefront Reference Architecture (SFRA). Tuttavia, per visualizzare in anteprima le pagine SFRA è possibile utilizzare lo strumento Anteprima sito di Storefront Toolkit in B2C Commerce.

Seguire questi passaggi di configurazione una tantum richiesti per ogni sito che utilizza Storefront Preview:

È necessario creare un client privato SLAS (Shopper Login and API Access Service) con gli ambiti sfcc.shopper-context.rw e sfcc.ts_ext_on_behalf_of per le istanze B2C Commerce utilizzate dallo storefront. Storefront Preview utilizza il client privato SLAS per impostare il contesto nello storefront. Il client privato SLAS può essere facilmente creato utilizzando SLAS Admin UI.

Seguire la procedura descritta nella guida Authorization for Shopper APIs (Autorizzazione per le Shopper API) per creare un client privato SLAS per ogni istanza B2C Commerce in cui si desidera utilizzare Storefront Preview:

Selezionare il tipo di app BFF o app Web nel campo Which App Type will be used? (Quale tipo di app verrà utilizzato?) per creare un client privato.
Specificare gli ambiti separati da uno spazio vuoto nel campo Enter the shopper scopes (Immettere gli ambiti acquirente): sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of

Copiare il segreto client generato automaticamente e visualizzato nella parte superiore della pagina dei risultati e l'ID client in modo da poterli utilizzare al passaggio successivo.

Per creare le variabili di ambiente MRT, richiamare l'endpoint API MRT projects_target_env_var_partial_update. Sostituire $SLAS_PRIVATE_CLIENT_ID e $SLAS_PRIVATE_CLIENT_SECRET con i valori copiati al passaggio 1. Sostituire $CC_SHORT_CODE con il valore di configurazione di codice breve proveniente da Business Manager. Per gestire le variabili di ambiente è anche possibile usare Runtime Admin. Vedere Variabili di ambiente.

La chiamata a questa API ridistribuisce il bundle attualmente distribuito. È necessario attendere il completamento della ridistribuzione prima di visualizzare l'anteprima del proprio storefront. Una volta completata la ridistribuzione, il bundle appare sotto l'intestazione Deployed Bundle (Bundle distribuito) nella directory del proprio progetto.

Per utilizzare Storefront Preview con uno storefront connesso alla propria istanza B2C Commerce, è necessario disporre di uno dei seguenti ruoli utente Account Manager: Amministratore di Business Manager o Utente di Business Manager. Per verificare se si dispone di uno di questi ruoli, controllare i ruoli in Account Manager.

Se non si dispone di nessuno dei ruoli richiesti, seguire le istruzioni Granting Permissions (Concessione autorizzazioni) per aggiungere istanze a proprio utente Account Manager.

Questo passaggio è richiesto solo per i progetti generati prima del rilascio di PWA Kit versione 2.8.0 e 3.2.0.
Con qualsiasi versione di PWA Kit, se si desidera integrare Storefront Preview con un CMS di terze parti è necessario aggiungere la prop onContextChange al componente StorefrontPreview. Se il componente StorefrontPreview è già stato aggiunto al proprio storefront, vedere Integrazione con un CMS di terze parti.

Affinché la comunicazione tra Runtime Admin e il proprio storefront funzioni, occorre stabilire un canale di comunicazione. L'operazione richiede due passaggi:

Per abilitare la comunicazione, eseguire il rendering del componente StorefrontPreview da PWA Kit React SDK al proprio storefront. Il componente StorefrontPreview inserisce uno script per stabilire la comunicazione con Runtime Admin. Questo script non influisce sulle prestazioni dello storefront perché viene caricato solo quando lo storefront è in esecuzione in Storefront Preview.
Ovunque si esegua il rendering di StorefrontPreview, è necessario definire la proprietà getToken, che deve restituire il token di accesso dell'acquirente corrente.

Facoltativamente, se si desidera integrare Storefront Preview con un CMS di terze parti, è possibile aggiungere la prop onContextChange al componente StorefrontPreview. Vedere Integrazione con un CMS di terze parti. Negli esempi seguenti, aggiungiamo la prop onContextChange e facciamo passare una funzione asincrona denominata handleContextChange. È possibile sostituire l'istruzione console.log nella funzione con la handleContextChange propria logica per rispondere alle modifiche di contesto. Personalizzare la funzione handleContextChange in base alle proprie esigenze specifiche. Il parametro newContext nella funzione conterrà le informazioni di contesto aggiornate.

Se si dispone della versione 2.8.x di PWA Kit, utilizzare il seguente codice nello storefront per stabilire un canale di comunicazione. Aggiungere il componente StorefrontPreview intorno al proprio componente IntlProvider nel file _app/index.jsx.

Se si dispone della versione 3.2.x di PWA Kit, utilizzare il seguente codice nello storefront per stabilire un canale di comunicazione. Aggiungere il componente StorefrontPreview intorno al proprio componente IntlProvider nel file _app/index.jsx.

Questo passaggio è richiesto solo per i progetti generati prima del rilascio di PWA Kit versione 2.8.0 e 3.2.0.
A partire dalle versioni 2.8.1 e 3.2.1, questo passaggio viene eseguito automaticamente nei nuovi progetti.
Questo passaggio non è necessario per i progetti che usano PWA Kit versione 2.8.0 o 3.2.0, poiché il middleware defaultPwaKitSecurityHeaders non esiste in tali versioni.

Per abilitare il canale di comunicazione, il proprio storefront deve:

Permettere a se stesso di essere incorporato in un iframe da Runtime Admin (runtime.commercecloud.com) e
Consentire il caricamento e l'esecuzione dello script menzionato al passaggio 4.

Abilitare il canale di comunicazione aggiungendo https://runtime.commercecloud.com alle direttive CSP (Content Security Policy) frame-ancestors, connect-src e script-src. Per fare in modo che questa operazione venga gestita automaticamente, importare e utilizzare il middleware defaultPwaKitSecurityHeaders fornito dal pacchetto pwa-kit-runtime.

Se è già stato aggiunto il componente StorefrontPreview allo storefront e ora si desidera eseguire l'integrazione con un CMS di terze parti, aggiungere la prop onContextChange al componente StorefrontPreview. Vedere Integrazione con un CMS di terze parti.

Negli esempi seguenti aggiungiamo la prop onContextChange e una funzione asincrona denominata handleContextChange. Nella funzione handleContextChange è possibile sostituire l'istruzione console.log con la propria logica per accomodare le modifiche del contesto. Personalizzare la funzione handleContextChange in base alle proprie esigenze specifiche. Il parametro newContext nella funzione conterrà le informazioni di contesto aggiornate.

Se si dispone di PWA Kit versione 2.8.x, utilizzare il codice seguente per aggiungere la prop onContextChange al file _app/index.jsx.

Se si dispone di PWA Kit versione 3.2.x, utilizzare il codice seguente e aggiungere la prop onContextChange al file _app/index.jsx.

Per utilizzare Storefront Preview, attenersi alla seguente procedura:

Aprire Runtime Admin nel browser e accedere utilizzando le credenziali di Account Manager.
Passare alla pagina degli ambienti del progetto e fare clic su Preview Site (Anteprima sito) accanto all'ambiente nel quale si desidera visualizzare l'anteprima del sito.

Si apre una nuova scheda che mostra lo storefront, con il modulo Storefront Preview nella barra laterale sinistra.
(Facoltativo) Scegliere la data e l'ora effettiva per il contesto di cui visualizzare l'anteprima. La data e l'ora visualizzate si basano sul fuso orario del computer e vengono quindi convertite in ora UTC prima dell'invio della richiesta che imposta il contesto. Se non si specificano una data e un'ora, l'anteprima rifletterà la data e l'ora correnti.
(Facoltativo) Inserire il codice sorgente che attiva la promozione (assegnazione della campagna) e i listini prezzi (assegnati al gruppo di codici sorgente) per il contesto di cui si desidera visualizzare l'anteprima.
(Facoltativo) Inserire gli ID di gruppo clienti impostati in Business Manager. Separare ogni ID con una virgola.
(Facoltativo) Inserire i qualificatori personalizzati che si applicano ai prezzi, alle promozioni o ai prodotti personalizzati impostati in Business Manager. Le chiavi dei qualificatori personalizzati devono essere univoche. È possibile definire fino a 20 qualificatori personalizzati.
Fare clic su Preview (Anteprima).

Ora è possibile navigare nello storefront utilizzando il contesto di cui si richiede l'anteprima.

Per facilitare la condivisione, l'URL nella scheda del browser viene aggiornato per includere i valori di contesto.

A volte è necessario interagire con lo storefront visualizzato in anteprima per visualizzare il comportamento previsto. Ad esempio, è possibile fare clic su una determinata taglia di abbigliamento per visualizzare l'eventuale prezzo scontato applicabile.

In caso di problemi con Storefront Preview è possibile abilitare i registri di Storefront Preview nell'ambiente MRT. In questo modo quando si fa clic sul pulsante Preview vengono stampati dei registri aggiuntivi per facilitare il debug dei problemi.

Per abilitare i registri di Storefront Preview, aggiungere la variabile di ambiente STOREFRONT_PREVIEW_DEBUG=1 all'ambiente MRT.

È possibile utilizzare i registri MRT con comando tail per leggere i log di Storefront Preview.

In questa sezione vengono suggerite soluzioni per gli errori comuni che possono verificarsi durante l'utilizzo di Storefront Preview.

A seconda del browser utilizzato, è possibile che si verifichino comportamenti diversi quando i cookie di terze parti non sono abilitati.

Chrome: Viene visualizzata una finestra modale con la dicitura "Anteprima non abilitata in questo storefront" e nello storefront viene visualizzato un file SecurityError.
Safari: Viene visualizzata una finestra modale con la dicitura "Impossibile inizializzare Storefront Preview" e lo storefront non è visibile.

Causa: Il proprio browser non ammette i cookie di terze parti su https://runtime.commercecloud.com.

Soluzione suggerita: Aggiornare le impostazioni del browser e le eventuali estensioni che consentono i cookie di terze parti su https://runtime.commercecloud.com.

Messaggio di errore durante il caricamento di Storefront Preview: "Preview is not enabled on this storefront!" (Anteprima non abilitata in questo storefront)

Causa: Nello storefront manca il file di script che abilita la comunicazione con Runtime Admin.

Soluzione suggerita: Seguire le istruzioni visualizzate nella finestra del messaggio di errore o completare le configurazioni del passaggio 4.

Messaggio di errore di risposta quando si fa clic sul pulsante Preview:

Soluzione suggerita: Completare le configurazioni del passaggio 1 e passaggio 2.

A seconda del browser in uso, è possibile che si verifichi un errore quando non si ha la corretta Content Security Policy.

Chrome: Viene visualizzata una finestra modale che indica "Anteprima non abilitata in questo storefront" e lo storefront visualizza una pagina di errore che indica "connessione rifiutata".
Safari: Viene visualizzata una finestra modale che indica "Anteprima non abilitata in questo storefront" e lo storefront non è visibile.

Causa: Lo storefront non consente l'opzione Runtime Admin all'interno della sua Content Security Policy.

Soluzione suggerita: Seguire le istruzioni del passaggio 5 per configurare correttamente la Content Security Policy.

La pagina iniziale caricata da Storefront Preview è il dominio configurato come Nome host esterno per l'ambiente.

Causa: Il nome host esterno non è configurato correttamente nelle impostazioni dell'ambiente.

Soluzione suggerita: Configurare il nome host esterno nella sezione Avanzate delle impostazioni di ambiente in modo che punti al dominio corretto.

Messaggio di errore di risposta visualizzato quando si fa clic sul pulsante Preview :

Soluzione suggerita: Completare il passaggio 3.

Messaggio di errore di risposta visualizzato quando si fa clic sul pulsante Preview :

Causa: Valori non corretti nelle variabili di ambiente MRT SLAS_PRIVATE_CLIENT_ID e SLAS_PRIVATE_CLIENT_SECRET o configurazione errata del client privato SLAS.

Soluzione suggerita: Completare il passaggio 1 e il passaggio 2.

Durante l'anteprima del sito, dopo aver aggiunto la proprietà onContextChange al componente StorefrontPreview, è possibile che vengano visualizzati messaggi di errore o risultati imprevisti.

Causa: Potrebbe esserci un problema con la funzione richiamata dalla prop onContextChange.

Soluzione suggerita: Rimuovere dal componente StorefrontPreview la prop onContextChange e corrispondente funzione richiamata. Visualizzare quindi l'anteprima del sito e controllare se si verificano gli stessi problemi. Altrimenti, eseguire il debug della funzione per risolvere eventuali errori. Ad esempio, è possibile:

Riaggiungere al componente StorefrontPreview la prop onContextChange prop e corrispondente funzione richiamata. Vedere Integrazione con un CMS di terze parti.
Esaminare l'attività di rete durante l'anteprima del sito e verificare se la richiesta di recupero invia i dati previsti.

Se ci sono ancora problemi dopo aver rimosso la prop onContextChange prop e corrispondente funzione richiamata, aprire una richiesta di assistenza.

Durante l'anteprima del sito, il contenuto non viene visualizzato come previsto e non si verifica nessuno degli errori sopra descritti. Ad esempio, i prezzi non cambiano in base ai valori immessi in Storefront Preview.

Causa: È possibile che non siano stati soddisfatti uno o più dei prerequisiti.

Soluzione suggerita: Confermare di aver soddisfatto tutti i prerequisiti. Se i prerequisiti sono soddisfatti e si riscontrano ancora problemi, aprire una richiesta di assistenza.