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.

Questo video mostra un esempio di come visualizzare l’anteprima dello storefront.

Anteprima storefront in un sito PWA Kit

Per utilizzare Storefront Preview, in primo luogo:

Crea il tuo sito utilizzando PWA Kit versione 2.8.4 o successiva oppure versione 3.6.0 o successiva. Storefront Preview non è disponibile nelle versioni di PWA Kit precedenti alla 2.8.4 o alla 3.2.x. Aggiornare il progetto per utilizzare PWA Kit 2.8.4 o 3.6.0 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.

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

• 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 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:

• 1. Creazione di un client privato SLAS per le proprie istanze B2C Commerce
• 2. Creazione di variabili di ambiente MRT con dettagli del client privato SLAS e codice breve Commerce API
• 3. Conferma che il proprio utente Account Manager disponga dell'accesso all'istanza B2C Commerce
• 4. Aggiunta del componente StorefrontPreview al proprio storefront
• 5. Aggiornamento delle intestazioni CSP (Content Security Policy) dello storefront

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

1curl "https://cloud.mobify.com/api/projects/$PROJECT/target/$ENVIRONMENT/env-var/" \
2--request 'PATCH' \
3--header 'Content-Type: application/json' \
4--header 'Accept: application/json' \
5--header "Authorization: Bearer $MOBIFY_API_KEY" \
6--data "{
7    \"CC_SHORT_CODE\": {\"value\": \"$CC_SHORT_CODE\"},
8    \"SLAS_PRIVATE_CLIENT_ID\": {\"value\": \"$SLAS_PRIVATE_CLIENT_ID\"},
9    \"SLAS_PRIVATE_CLIENT_SECRET\": {\"value\": \"$SLAS_PRIVATE_CLIENT_SECRET\"}
10}"

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.

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. Si noti che onContextChange è disponibile solo in PWA Kit versione 3.6.x o successiva. 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.

1// app/component/_app/index.jsx
2import StorefrontPreview from 'pwa-kit-react-sdk/storefront-preview'
3
4const App = () => {
5  // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
6  const handleContextChange = async (newContext) => {
7    console.log('Context changed:', newContext)
8  }
9
10  return (
11    <Box className="sf-app" {...styles.container}>
12      <StorefrontPreview
13        getToken={() => window.localStorage.getItem('token')}
14      >
15        <IntlProvider>
16          <CurrencyProvider currency={currency}>...</CurrencyProvider>
17        </IntlProvider>
18      </StorefrontPreview>
19    </Box>
20  )
21}
22
23export default App

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.

1// app/component/_app/index.jsx
2import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components'
3
4const App = () => {
5  const {getTokenWhenReady} = useAccessToken()
6  // Optionally, include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
7  const handleContextChange = async (newContext) => {
8    console.log('Context changed:', newContext)
9  }
10
11  return (
12    <Box className="sf-app" {...styles.container}>
13      <StorefrontPreview
14        getToken={getTokenWhenReady}
15        //Pass the optional handleContextChange function to the onContextChange prop.
16        onContextChange={handleContextChange}
17      >
18        <IntlProvider>
19          <CurrencyProvider currency={currency}>...</CurrencyProvider>
20        </IntlProvider>
21      </StorefrontPreview>
22    </Box>
23  )
24}
25
26export default App

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.

1// app/ssr.js
2// Using PWA Kit version 3.6.x
3import {getRuntime} from '@salesforce/pwa-kit-runtime/ssr/server/express'
4import {defaultPwaKitSecurityHeaders} from '@salesforce/pwa-kit-runtime/utils/middleware'
5// Using PWA Kit version 2.8.x
6import {getRuntime} from 'pwa-kit-runtime/ssr/server/express'
7import {defaultPwaKitSecurityHeaders} from 'pwa-kit-runtime/utils/middleware'
8
9const runtime = getRuntime()
10const {handler} = runtime.createHandler(options, (app) => {
11    // Set default HTTP security headers required by PWA Kit / Storefront Preview
12    app.use(defaultPwaKitSecurityHeaders)
13    // ...

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 3.6.x o successiva, utilizzare il codice seguente e aggiungere la prop onContextChange nel _app/index.jsx file.

1// app/component/_app/index.jsx
2import {StorefrontPreview} from '@salesforce/commerce-sdk-react/components'
3
4const App = () => {
5  const {getTokenWhenReady} = useAccessToken()
6  // Include an asynchronous function such as handleContextChange to integrate with a third-party CMS.
7  const handleContextChange = async (newContext) => {
8    console.log('Context changed:', newContext)
9  }
10
11  return (
12    <Box className="sf-app" {...styles.container}>
13      <StorefrontPreview
14        getToken={getTokenWhenReady}
15        // Pass the handleContextChange function to the onContextChange prop.
16        onContextChange={handleContextChange}
17      ></StorefrontPreview>
18    </Box>
19  )
20}
21
22export default App

Vedere Esempio di utilizzo per un video che mostra come visualizzare in anteprima lo storefront.

Per utilizzare Storefront Preview, attenersi alla seguente procedura:

1. Aprire Runtime Admin nel browser e accedere utilizzando le credenziali di Account Manager.

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

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

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

5. (Facoltativo) Inserire gli ID di gruppo clienti impostati in Business Manager. Separare ogni ID con una virgola.

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

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

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:

1400 error: Missing required environment variables:
2CC_SHORT_CODE,SLAS_PRIVATE_CLIENT_ID,SLAS_PRIVATE_CLIENT_SECRET

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 :

1403 error: You don't have access to the shopper's tenant

Soluzione suggerita: Completare il passaggio 3.

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

1400 error: Failed to get trusted system token, check your SLAS private client

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.

j

Inizia

Introduzione a Composable Storefront

Utilizzo di uno storefront componibile in un'implementazione ibrida

Framework di PWA Kit

Competenze tecniche necessarie

Ask the Community

Preparazione

Creazione del sito

Le migliori risorse per il proprio team di commercianti

Storefront Preview

Dati e analisi

Test, lancio e monitoraggio

Manutenzione

Italiano

English

日本語

中文

繁體中文

Français

Deutsch

Italiano

한국어

Português

Español (México)