Storefront Preview

您可以使用 Storefront Preview 來查看 Progressive Web App (PWA) Kit 網站在不同情境下 (例如指定的來源代碼、客戶群組或特定日期/時間) 的外觀。例如，如果您想預覽您的網站在即將到來的促銷期間的外觀，您可以使用此功能。

黑色星期五／網路星期一促銷即將到來？請在 Staging 環境中預覽網站變更。然後，在將變更部署到 Production 環境之前，請確保您對產品、定價、行銷策略等方面的變更按照您的預期進行。

此外，您還可以將 Storefront Preview 與第三方內容管理系統 (CMS) 整合。例如，假設您有一個由 CMS 管理的節日促銷橫幅。您可以允許 CMS 辨識目前情境，例如生效日期和時間，以便網站預覽能顯示正確的內容，例如指定時段的節日促銷橫幅。

Storefront Preview 可於 Runtime Admin 取得。本指南介紹如何設定、使用 Storefront Preview 並對其進行疑難排解。

要使用 Storefront Preview，您必須首先：

  • 使用 PWA Kit 2.8.3 或更高版本，或 3.2.x 搭配 @salesforce/commerce-sdk-react@1.4.0 或 @salesforce/retail-react-app@2.4.0 來建立您的網站。Storefront Preview 在早於 2.8.3 或 3.2.x 的 PWA Kit 版本中不可用。根據目前的主要版本，將專案升級為使用 PWA Kit 2.8.3 或 3.2.x。
  • 以「唯讀」以外的任何角色存取 Runtime Admin 中的專案。如果您沒有存取權限，請要求具有 Managed Runtime (MRT) 管理員角色的人員來協助您。
  • 在 Business Manager 中啟用購物者情況。
  • 根據要在 Storefront Preview 中驗證的功能，設定您的網站。範例：
    • 使用 Business Manager 中的客戶群組來設定自訂限定詞和客戶群組 ID，以套用個人化定價、產品或促銷的規則。
    • 若要獲得個人化的購物者體驗，請將原始程式碼設定為可呼叫 Shopper Context 端點。這是必要步驟，因為 Storefront Preview 會使用內容資訊進行個人化。
    • 設定要在特定日期提供的定價。這樣，當您在 Storefront Preview 中選擇該日期時，便會顯示您指定的定價。
  • 請依照設定 Storefront Preview 一節中說明的設定步驟進行操作。
  • 設定您的瀏覽器以允許 https://runtime.commercecloud.com 上的第三方 Cookie。

或者，如果要將 Storefront Preview 與第三方 CMS 整合，可以編寫函數。請參閱將 StorefrontPreview 元件新增至網店和與第三方 CMS 整合。

您編寫的與第三方 CMS 整合的函式必須是非同步的。這有助於避免在預覽網站時出現意外結果。

您可以將 Storefront Preview 與最新版本的 Chrome 或 Safari 搭配使用。您的瀏覽器必須允許 https://runtime.commercecloud.com 存取第三方 Cookie。如果您不啟用第三方 Cookie，Storefront Preview 將無法運作。

瞭解如何為 Chrome 和 Safari 啟用第三方 Cookie。
  • Storefront Preview 中顯示的資料和體驗並不一定反映購物者的體驗。購物者個人化需要在 PWA Kit 專案中使用 Shopper Context API。進一步瞭解 Shopper Context。
  • Storefront Preview 會顯示您網站上的訪客使用者所看到的網店頁面。例如，訪客使用者可以查看產品或行銷內容、定價、促銷、產品清單或產品顯示頁面。您不會看到登入使用者看到的內容，例如帳戶資訊或購物車。
  • Storefront Preview 適用於 PWA Kit 頁面，但不適用於 Storefront Reference Architecture (SFRA) 頁面。但是，您可以使用 B2C Commerce 中的 Storefront Toolkit 網站預覽工具來預覽 SFRA 頁面。

請遵循下列一次性設定步驟，每個使用 Storefront Preview 的網站都必須完成：

您必須為網店使用的 B2C Commerce 執行個體建立範圍為 sfcc.shopper-context.rw、sfcc.ts_ext_on_behalf_of 的 Shopper Login and API Access Service (SLAS) 私人用戶端。Storefront Preview 使用 SLAS 私人用戶端來設定網店中的內容。可以使用 SLAS Admin UI，輕鬆建立 SLAS 私人用戶端。

依照 Shopper API 授權指南中的步驟，為要使用 Storefront Preview 的每個 B2C Commerce 執行個體建立 SLAS 私人用戶端：

  • 在 [Which App Type will be used?] (要使用哪個應用程式類型？) 欄位中，選擇應用程式類型 [BFF or Web App] (BFF 或網路應用程式) 來建立私人用戶端。
  • 在 [Enter the shopper scopes] (輸入購物者範圍) 欄位中，指定以空格分隔的範圍：sfcc.shopper-context.rw sfcc.ts_ext_on_behalf_of

複製結果頁面頂部顯示的自動產生的用戶端金鑰和用戶端 ID，以便您可以在下一步中使用它們。

若要建立 MRT 環境變數，請呼叫 MRT API 端點 projects_target_env_var_partial_update。 將 $SLAS_PRIVATE_CLIENT_ID、$SLAS_PRIVATE_CLIENT_SECRET 替換為您在步驟 1 中複製的值。將 $CC_SHORT_CODE 替換為 Business Manager 中的短代碼設定值。您還可以使用 Runtime Admin 來管理環境變數。請參閱環境變數。

呼叫此 API 會重新部署目前已部署的套件。必須等待重新部署完成，才能預覽網店。當重新部署完成後，套件將會在專案目錄的標題 Deployed Bundle (已部署套件) 下出現。

要將 Storefront Preview 用於連接到 B2C Commerce 執行個體的網店，您必須具有以下 Account Manager 使用者角色之一：Business Manager 管理員或 Business Manager 使用者。若要驗證您是否具有這些角色之一，請檢查您在 Account Manager 中的角色。

如果您不具備任一所需角色，請依照這些授予權限說明，將執行個體新增至您的 Account Manager 使用者。

  • 只有在 PWA Kit 版本 2.8.0、3.2.0 發佈之前產生的專案，才需要此步驟。
  • 對於任何版本的 PWA Kit，如果要將 Storefront Preview 與第三方 CMS 整合，則必須將 onContextChange prop 新增到 StorefrontPreview 元件中。如果您已將 StorefrontPreview 元件新增至網店，請參閱與第三方 CMS 整合。

為了讓 Runtime Admin 和您的網店之間能夠正常通訊，請建立通訊通道。這涉及兩個步驟：

  • 若要啟用通訊，請在網店中，從 PWA Kit React SDK 轉譯 StorefrontPreview 元件。StorefrontPreview 元件注入一個指令碼來與 Runtime Admin 建立通訊。此指令碼不會影響網店的效能，因為它只會在網店於 Storefront Preview 模式運作時載入。
  • 無論您在何處轉譯 StorefrontPreview，都必須定義 getToken prop，該屬性必須傳回目前購物者的存取權杖。

或者，如果您想要將 Storefront Preview 與第三方 CMS 整合，您可以將 onContextChange prop 新增至 StorefrontPreview 元件。請參閱與第三方 CMS 整合。在下面的範例中，我們新增了 onContextChange prop，並向其傳遞一個名為 handleContextChange 的非同步函式。您可以將 handleContextChange 函式中的 console.log 陳述式替換為您自己的邏輯，以回應情境變更。依您的特定需求自訂 handleContextChange 函式。函式中的 newContext 參數將包含更新的情境資訊。

如果您的 PWA Kit 版本是 2.8.x，請在網店中使用以下程式碼建立通訊通道。在 _app/index.jsx 檔案中，將 StorefrontPreview 元件加至 IntlProvider 元件周圍。

如果您的 PWA Kit 版本是 3.2.x，請在網店中使用以下程式碼建立通訊通道。在 _app/index.jsx 檔案中，將 StorefrontPreview 元件加至 IntlProvider 元件周圍。

  • 只有在 PWA Kit 版本 2.8.0、3.2.0 發佈之前產生的專案，才需要此步驟。
  • 從 2.8.1 和 3.2.1 版本開始，此步驟將在新專案中自動完成。
  • 使用 PWA Kit 2.8.0 或 3.2.0 版本的專案 不 需要執行此步驟，因為這些版本中不存在 defaultPwaKitSecurityHeaders 中介軟體。

要啟用通訊通道，您的網店必須：

  • 允許由 Runtime Admin (runtime.commercecloud.com) 將自身嵌入到 iframe 中，而且
  • 允許載入並執行步驟 4 中提到的指令碼。

將 https://runtime.commercecloud.com 新增至內容安全性政策 (CSP) frame-ancestors、connect-src、script-src 指令，來啟用通訊通道。若要自動處理此部分，請匯入並使用 pwa-kit-runtime 套件提供的 defaultPwaKitSecurityHeaders 中介軟體。

如果您已將 StorefrontPreview 元件新增至網店，現在想要與第三方 CMS 整合，請將 onContextChange prop 新增至 StorefrontPreview 元件。請參閱與第三方 CMS 整合。

在下面的範例中，我們新增了 onContextChange prop 和名為 handleContextChange 的非同步函式。您可以將 handleContextChange 函式中的 console.log 陳述式替換為您自己的邏輯，以回應情境變更。依您的特定需求自訂 handleContextChange 函式。函式中的 newContext 參數將包含更新的情境資訊。

如果您的 PWA Kit 版本是 2.8.x，請使用下列程式碼，在 _app/index.jsx 檔案中新增 onContextChange prop。

如果您的 PWA Kit 版本是 3.2.x，請使用下列程式碼，在 _app/index.jsx 檔案中新增 onContextChange prop。

請按照以下步驟來使用 Storefront Preview：

  1. 在瀏覽器中開啟 Runtime Admin，並使用您的 Account Manager 憑證登入。

  2. 前往專案的環境頁面，然後按一下要預覽網站的環境旁的 [Preview Site] (預覽網站)。

    新的分頁會開啟，顯示網店，左側欄位顯示 Storefront Preview 表格。

  3. (選擇性) 選擇要預覽的內容的生效日期和時間。顯示的日期和時間會根據您電腦的時區，然後轉換為 UTC 時間，再傳送可設定情境的要求。如果未指定日期和時間，則預覽將反映目前的日期和時間。

  4. (選擇性) 輸入可觸發促銷 (宣傳活動指派) 的來源代碼和要預覽的內容的價格表 (指派到來源代碼群組)。

  5. (選擇性) 輸入在 Business Manager 中設定的客戶群組 ID。請用逗號分隔每個 ID。

  6. (選擇性) 輸入適用於 Business Manager 中設定的個人化價格、產品或促銷的自訂限定條件。自訂限定條件鍵必須是唯一的。最多可以定義 20 個自訂限定條件。

  7. 按一下 Preview (預覽)。

    現在，您可以使用要預覽的情境來瀏覽網店。

    為方便共用，瀏覽器分頁中的 URL 已更新為包含情境值。

有時，您必須與預覽的網店進行互動，才能查看預期的行為。例如，您可以點選特定尺碼的衣服，以查看任何適用的折扣價格。

如果您遇到 Storefront Preview 的任何問題，可以在 MRT 環境中啟用 Storefront Preview 記錄檔。 當您按一下 Preview (預覽) 按鈕時，這會列印額外的日誌以協助您偵錯問題。

若要啟用 Storefront Preview 記錄檔，請將 MRT 環境變數 STOREFRONT_PREVIEW_DEBUG=1 AAA 新增至您的 MRT 環境。

您可以使用 MRT 記錄檔末尾內容來讀取 Storefront Preview 日誌。

本節針對使用 Storefront Preview 時可能遇到的常見錯誤，提供建議的解決方案。

根據瀏覽器而定，在未啟用第三方 Cookie 時，您可能會遇到不同的行為。

  • **Chrome：**此時將出現互動視窗 (modal)，顯示「這個網店沒有啟用預覽功能」，而網店顯示 SecurityError。
  • **Safari：**此時將出現互動視窗 (modal)，顯示「無法初始化網店預覽」，而網店不可見。

**原因：**您的瀏覽器不允許 https://runtime.commercecloud.com 使用第三方 Cookie。

**建議的解決方案：**更新您的瀏覽器設定和您可能使用的任何擴充功能，以允許 https://runtime.commercecloud.com 上的第三方 Cookie。

載入 Storefront Preview 時出現錯誤訊息："Preview is not enabled on this storefront!"

**原因：**網店缺少可啟用與 Runtime Admin 通訊的指令碼檔案。

**建議的解決方案：**請依照錯誤訊息視窗中顯示的說明進行操作，或完成步驟 4 中的設定。

按一下 [Preview] (預覽) 按鈕時，傳回錯誤訊息：

**建議的解決方案：**完成步驟 1 和步驟 2 中的設定。

根據瀏覽器而定，如果沒有正確的內容安全性政策，您可能會遇到錯誤。

  • **Chrome：**此時將出現互動視窗 (modal)，顯示「這個網店沒有啟用預覽功能」，而網店將顯示錯誤頁面「拒絕連接」。
  • **Safari：**此時將出現互動視窗 (modal)，顯示「這個網店沒有啟用預覽功能」，而網店不可見。

**原因：**您的網店在其內容安全性政策中不允許 Runtime Admin。

**建議的解決方案：**依照步驟 5 中的說明，正確設定您的內容安全性政策。

Storefront Preview 載入的初始頁面是設定為環境的外部主機名稱的網域。

**原因：**未在環境設定中正確配置外部主機名稱。

**建議的解決方案：**在 environment settings 的 Advanced 部分中配置外部主機名稱以指向正確的網域。

按一下 [Preview] (預覽) 按鈕時，看到錯誤訊息傳回：

**建議的解決方案：**完成步驟 3。

按一下 [Preview] (預覽) 按鈕時，看到錯誤訊息傳回：

**原因：**MRT 環境變數 SLAS_PRIVATE_CLIENT_ID 和 SLAS_PRIVATE_CLIENT_SECRET 中的值不正確，或 SLAS 私密用戶端設定錯誤。

**建議的解決方案：**完成步驟 1 和步驟 2。

將 onContextChange prop 新增至 StorefrontPreview 元件後，預覽網站時，您可能會收到錯誤訊息或意外結果。

原因：onContextChange prop 呼叫的函式可能有問題。

**建議的解決方案：**從 StorefrontPreview 元件中移除 onContextChange prop 及其呼叫的函式。然後，預覽您的網站，看看是否出現相同的問題。如果沒有問題，請偵錯函式以解決任何錯誤。例如，您可以：

  • 將 onContextChange prop 及其回呼函式新增至 StorefrontPreview 元件。請參閱與第三方 CMS 整合。
  • 在預覽網站時檢查網路活動，查看擷取要求是否傳送了預期的資料。

如果刪除 onContextChange prop 及其呼叫的函式後仍有問題，請建立支援案例。

預覽網站時，內容未如預期顯示，但沒有出現上述錯誤。例如，價格不會根據您在 Storefront Preview 中輸入的值而變化。

**原因：**您可能沒有完成一或多個先決條件。

**建議的解決方案：**確認您已完成所有先決條件。如果您這樣做了但仍然遇到問題，請建立支援案例。