Lancio dello storefront

Questa guida descrive come avviare uno storefront di Progressive Web App (PWA) Kit e renderlo accessibile dal suo indirizzo web pubblico ufficiale.

In questa guida verrà utilizzato uno storefront di esempio con i seguenti attributi:

  • URL di Production: https://www.example.com
  • ID progetto: example
  • ID ambiente: staging e production

Prima di eseguire i comandi, sostituire i segnaposto con i valori effettivi. I segnaposto sono formattati nel seguente modo: $PLACEHOLDER.

Vedere Decidere quale rete CDN utilizzare.

In questa guida si presuppone che l'utente abbia accesso all'applicazione web Runtime Admin e a Managed Runtime API per l'esecuzione delle attività amministrative. Per ottenere l'accesso a questi strumenti, rivolgersi all'amministratore Commerce Cloud e chiedere di aggiungere uno dei seguenti ruoli all'account che utilizza Account Manager: Managed Runtime User (Utente Managed Runtime) o Managed Runtime Admin (Amministratore Managed Runtime).

Per effettuare richieste a Managed Runtime API è necessario includere una chiave API nell'intestazione Authorization della richiesta HTTP con il valore Bearer $API_KEY. In tutte le richieste di esempio fornite, non dimenticare di sostituire $API_KEY con la chiave API effettiva.

Per individuare la chiave API, accedere a Runtime Admin e passare alla pagina Account Settings (Impostazioni account).

Importante: Considerare la propria chiave API come una password perché consente agli script di completare le operazioni per proprio conto.

Per creare e aggiornare i record CNAME è necessario avere accesso al provider DNS e, a seconda dei casi, anche al provider CDN di terze parti.

Il termine "Mobify" compare in alcuni punti di questa guida. Mobify è il nome dell'azienda che in origine ha sviluppato la tecnologia successivamente adottata per PWA Kit e Managed Runtime. Nel 2020 Salesforce ha acquisito Mobify insieme a tutte le relative tecnologie.

Il nome del brand Mobify compare nel dominio mobify-storefront.com in cui viene ospitato lo storefront e nel dominio cloud.mobify.com utilizzato da Managed Runtime API.

Se occorre aggiungere una logica condizionale che modifichi il comportamento del sito in base al dominio utilizzato, risulta più facile testarla quando il server di sviluppo locale può utilizzare un dominio personalizzato. Perché dovrebbe essere necessario aggiungere questo tipo di logica? Si pensi, ad esempio, alla necessità di cercare un ID client SLAS diverso a seconda del dominio.

Per eseguire il server di sviluppo locale utilizzando un dominio personalizzato:

  1. Modificare il DNS del computer locale per risolvere il dominio personalizzato a 127.0.0.1 (localhost).
  2. Modificare ssr.js.
  3. Nelle options passate a runtime.createHandler, impostare la porta su 80.
  4. Eseguire EXTERNAL_DOMAIN_NAME=www.example.com npm start sostituendo il valore di example.com con il dominio personalizzato. L'esecuzione del server sulla porta 80 a volte può richiedere privilegi amministrativi.

Le richieste dal browser al dominio personalizzato ora vengono risolte e instradate al server di sviluppo locale.

Il processo di lancio è uguale sia per gli ambienti Staging sia per gli ambienti Production. L'unica differenza è rappresentata dal nome di dominio e dall'ambiente Managed Runtime utilizzato.

Si consiglia vivamente di eseguire il processo di lancio prima in un ambiente Staging e poi ripeterlo in un ambiente Production. Questi passaggi dovrebbero essere completati non appena si inizia un progetto PWA Kit e almeno due settimane prima della data di lancio.

Per le istruzioni fornite, si supponga il lancio di uno storefront su staging.example.com con ID di progetto example in Managed Runtime e il proprio bundle distribuito in un ambiente denominato staging.

Utilizzare Runtime Admin o Managed Runtime API per creare un ambiente denominato staging per provare il lancio dello storefront.

Di seguito è riportato un esempio di richiesta che utilizza l'endpoint projects_target_create per creare un ambiente. Sostituire example nella richiesta con la stringa dell'ID di progetto effettivo e $API_KEY con la propria chiave API:

Per le istruzioni sulla creazione di un ambiente con Runtime Admin, consultare la guida Amministrazione in Managed Runtime.

Molte implementazioni di PWA Kit effettuano richieste a OCAPI o controller in aggiunta a B2C Commerce API.

Assicurarsi che la propria istanza B2C Commerce sia raggiungibile da Managed Runtime.

Per rendere le API raggiungibili, in genere è necessario configurare la rete eCDN in modo da rendere disponibile l'istanza B2C Commerce su un dominio alternativo, ad esempio ecom.example.com. Per ulteriori informazioni, fare riferimento alla documentazione relativa all'impostazione e alla configurazione della eCDN.

Dopo aver configurato il dominio, aggiornare le impostazioni proxy dell'ambiente per utilizzarlo. Per ulteriori informazioni, consultare la guida Invio delle richieste a un proxy.

Questo passaggio non è necessario se si utilizza una CDN o una eCDN di terze parti. Consultare la documentazione del fornitore della rete CDN per la configurazione dei certificati.

Se si instrada il traffico direttamente alla rete CDN di Managed Runtime, quest'ultimo emette e gestisce i certificati TLS per conto dell'utente.

Per consentire a Managed Runtime di emettere un certificato, è necessario:

  • Scegliere i domini che desidera utilizzare per il proprio storefront. Ad esempio, staging.example.com e www.example.com. Sono supportati domini con caratteri jolly come *.example.com . I certificati di dominio specifici verranno emessi solo per i domini associati agli ambienti Staging e Production.
  • Assicurati che i record del CAA dominio siano impostati per consentire ad AWS di emettere certificati.
  • Contattare Salesforce Customer Support e fornire i domini di certificato desiderati. Aspettati un'inversione di tendenza di 1-2 giorni lavorativi.
  • Salesforce fornisce un record CNAME utilizzato per convalidare la proprietà del dominio. È necessario creare il record fornito entro 24 ore dalla ricezione delle informazioni.

Il runtime gestito rinnova automaticamente i certificati TLS a condizione che:

  • Il record CNAME rimane al suo posto per convalidare la proprietà
  • Il certificato TLS è utilizzato da almeno 1 ambiente

Questo passaggio non è necessario se si utilizza una CDN o una eCDN di terze parti.

Ridurre la durata TTL di staging.example.com a un minuto. La riduzione della durata TTL accelera il processo di migrazione DNS e, in caso di errore, consente di eseguire rapidamente il rollback.

È possibile verificare il TTL utilizzando il [dig]comando (https://en.wikipedia.org/wiki/Dig_(command) ):

Impostare l'intestazione di controllo dell'accesso di un ambiente utilizzando Managed Runtime UI in Impostazioni di controllo di accesso o l'APIaccess_control_header. In questo esempio utilizziamo l'API per impostare un'intestazione di controllo dell'accesso con il valore di intestazione 25pn5dec7f1c. Vedere Intestazioni di controllo dell'accesso.

Il valore dell'intestazione del controllo di accesso verrà utilizzato durante l'esecuzione del cutover per impedire l'accesso diretto all'ambiente.

Configurare l'ambiente per ricevere il traffico dall'host staging.example.com.

Aggiornare le impostazioni ssr_external_domain e ssr_external_hostname dell'ambiente utilizzando l'APIprojects_target_partial_update:

Dopo questa fase, l'ambiente non è più accessibile sul proprio dominio mobify-storefront.com.

Verificare che le nuove impostazioni siano effettive utilizzando un comando cURL che effettui una richiesta con spoofing DNS:

Il processo di migrazione è diverso a seconda che si utilizzi una rete CDN di terze parti, una eCDN o la CDN di Managed Runtime.

Configurare l'ambiente Managed Runtime come origine nella propria rete CDN:

  • impostare l'intestazione Host in modo che corrisponda all'ambiente {{project}}-{{environment}}.mobify-storefront.com
  • inoltrare il metodo di richiesta
  • inoltrare il percorso (inclusa la stringa di query)
  • inoltrare le intestazioni
  • inoltrare il corpo
  • inoltrare tutto il traffico su HTTPS
  • eseguire le istruzioni delle intestazioni di caching HTTP
  • impostare il valore dell'intestazione x-sfdc-access-control se configurato per il proprio ambiente

Per indicazioni dettagliate, fare riferimento alla documentazione del provider CDN.

Managed Runtime instrada le richieste agli ambienti utilizzando l'intestazione HTTP Host. Le richieste con un host non corretto vengono rifiutate con una risposta HTTP 403 Bad Request.

Considerare la possibilità di aggiungere di un handler per rispecchiare le richieste HTTP e verificare che la CDN sia configurata correttamente:

Considerare inoltre la possibilità di aggiungere un proxy con httpbin.org/anything per verificare che le intestazioni passate ai proxy vengano inviate correttamente.

In caso di problemi, usare le tecniche descritte in Debug delle app PWA Kit.

Aggiornare le regole di routing eCDN per instradare il traffico al proprio ambiente Managed Runtime. Per ulteriori informazioni, consultare la guida alle Regole MRT eCDN. È inoltre possibile configurare le regole di routing MRT in Business Manager.

Utilizzare l'API upsertOriginHeaderModification per impostare headerValue sugli stessi valori usati nel passaggio 5. In questo modo, è consentito solo il traffico proveniente dalla eCDN. In questo esempio utilizziamo l'API per impostare un'intestazione di controllo dell'accesso con il valore di intestazione .

Eseguire una migrazione DNS per puntare il proprio dominio dall'origine precedente alla CDN di Managed Runtime.

Il dominio della CDN di Managed Runtime segue la convenzione {{project}}-{{environment}}-cdn.mobify-storefront.com in cui {{project}} è l'ID del proprio progetto e {{environment}} è l'ID del proprio ambiente.

Aggiornare il record CNAME DNS di staging.example.com in example-staging-cdn.mobify-storefront.com.

Aprire il browser web e passare a staging.example.com.

Congratulazioni. Il lancio è stato completato. 🥳

Dopo aver completato questa procedura per un sito Staging, è possibile ripeterla per il dominio e l'ambiente Production.

A questo punto, con l'aiuto del Customer Success Group, monitorare il traffico del sito per verificare che il lancio sia andato a buon fine. L'obiettivo è verificare che durante il lancio tutto proceda come previsto.

Dopo il lancio, i clienti con piano Signature Success Plan hanno diritto al monitoraggio del sito proattivo. Per usufruire di questo ulteriore servizio di monitoraggio, è necessario contrassegnare l'ambiente come production. Per ulteriori informazioni, vedere la sezione relativa agli ambienti in Managed Runtime.

  • L'impostazione del target ssr_external_hostname controlla da quale host l'ambiente riceve traffico. Se l'intestazione Host HTTP di una richiesta non corrisponde a questo valore, la richiesta non va a buon fine e viene restituito un errore 403.
  • Attualmente Salesforce non supporta gli URL di storefront contenenti un dominio semplice, ad esempio example.com (senza sottodominio www). Per utilizzare un dominio semplice, è necessario impostare un server per il reindirizzamento delle richieste da tale dominio al proprio CNAME.