Storefront Preview

可以使用 Storefront Preview 查看 Progressive Web App (PWA) Kit 站点根据上下文（如指定的源代码、客户组或特定日期或时间）设置的外观。例如，如果您想预览站点在即将开始的促销中的显示方式，则可以使用此功能。

黑色星期五/网络星期一促销即将到来？在准备环境中预览站点更改。然后，在将更改部署到生产环境之前，请确保对产品、定价和营销策略等内容的更改按预期方式工作。

此外，您还可以将 Storefront Preview 与第三方内容管理系统 (CMS) 集成。例如，假设您有一个由 CMS 管理的假日销售横幅。您可以允许 CMS 识别当前上下文，例如生效日期和时间，以便您的站点预览显示指定时间段的正确内容，例如假日促销横幅。

Storefront Preview 在 Runtime Admin 中可用。本指南介绍如何配置、使用 Storefront Preview 并解决其问题。

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

  • 使用 PWA Kit 2.8.3 或更高版本，或者带有 @salesforce/retail-react-app@2.4.0 或 @salesforce/commerce-sdk-react@1.4.0 的 3.2.x 构建站点。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 中启用 Shopper Context。
  • 根据要在 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 实例创建一个 Shopper Login and API Access Service (SLAS) 专用客户端，其范围为 sfcc.shopper-context.rw 和 sfcc.ts_ext_on_behalf_of。Storefront Preview 使用 SLAS 专用客户端在网店中设置上下文。可以使用 SLAS Admin UI 轻松创建 SLAS 专用客户端。

按照购物者 API 授权指南 中的步骤，为要使用 Storefront Preview 的每个 B2C Commerce 实例创建 SLAS 专用客户端：

  • 在**将使用哪种应用类型？**字段中选择应用类型 BFF 或 Web 应用以创建专用客户端。
  • 在输入购物者范围字段中指定用空格分隔的范围： 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 会重新部署当前已部署的捆绑包。必须等待重新部署完成，然后才能预览网店。成功完成重新部署后，捆绑包将显示在项目目录中**“已部署的捆绑包”**标题下。

要将 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 道具添加到 StorefrontPreview 组件中。如果您已将 StorefrontPreview 组件添加到网店，请参阅与第三方 CMS 集成。

要使 Runtime Admin 和您的网店之间的通信正常工作，请建立通信渠道。这涉及两个步骤：

  • 若要启用通信，请在网店中渲染 PWA Kit React SDK 中的组件 StorefrontPreview。该 StorefrontPreview 组件注入脚本以与 Runtime Admin 建立通信。此脚本不会影响网店的性能，因为它仅在网店在 Storefront Preview 中运行时加载。
  • 无论您在哪里渲染 StorefrontPreview，都必须定义 getToken 道具，它必须返回当前购物者的访问令牌。

或者，如果要将 Storefront Preview 与第三方 CMS 集成，则可以将 onContextChange 道具添加到 StorefrontPreview 组件中。请参阅与第三方 CMS 集成。在下面的示例中，我们添加 onContextChange 道具并向其传递一个名为 handleContextChange 的异步函数。您可以将函数 handleContextChange 中的语句 console.log 替换为自己的逻辑，以响应上下文更改。根据您的具体要求自定义 handleContextChange 函数。函数中的 newContext 参数将包含更新的上下文信息。

如果您具有 PWA Kit 版本 2.8.x，请在网店中使用以下代码来建立通信通道。在 _app/index.jsx 文件中的 IntlProvider 组件周围添加 StorefrontPreview 组件。

如果您有 PWA Kit 版本 3.2.x，请在网店中使用以下代码建立通信通道。在 _app/index.jsx 文件中的 IntlProvider 组件周围添加 StorefrontPreview 组件。

  • 只有在 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 中提到的脚本。

通过向内容安全政策 (CSP) frame-ancestors、connect-src 和 script-src 指令添加 https://runtime.commercecloud.com 来启用通信通道。若要自动处理此问题，请导入并使用 defaultPwaKitSecurityHeaders 包提供的 pwa-kit-runtime 中间件。

如果您已经将 StorefrontPreview 组件添加到网店，并且现在想要与第三方 CMS 集成，请将 onContextChange 道具添加到 StorefrontPreview 组件中。请参阅与第三方 CMS 集成。

在下面的示例中，我们添加了 onContextChange 道具和一个名为 handleContextChange的异步函数。您可以将函数 handleContextChange 中的语句 console.log 替换为自己的逻辑，以响应上下文更改。根据您的具体要求自定义 handleContextChange 函数。函数中的 newContext 参数将包含更新的上下文信息。

如果您有 PWA Kit 版本 2.8.x，请使用以下代码在 _app/index.jsx 文件中添加 onContextChange 道具。

如果您有 PWA Kit 版本 3.2.x，请使用以下代码在 _app/index.jsx 文件中添加 onContextChange 道具。

请按照以下步骤使用 Storefront Preview：

  1. 在浏览器中打开 Runtime Admin，然后使用 Account Manager 登录信息登录。

  2. 导航到项目的环境页面，然后单击要预览站点的环境旁边的**“预览站点”**。

    此时会打开一个会显示网店的新选项卡，左侧边栏上有 Storefront Preview 窗体。

  3. （可选）选择要预览的上下文的生效日期和时间。显示的日期和时间基于您计算机的时区，然后转换为 UTC 时间，然后发送设置上下文的请求。如果未指定日期和时间，预览将反映当前日期和时间。

  4. （可选）输入要预览的上下文的触发促销的源代码（活动分配）和价目表（分配至追踪代码组）。

  5. （可选）输入在 Business Manager 中设置的客户组 ID。用逗号分隔每个 ID。

  6. （可选）输入适用于在 Business Manager 中设置的个性化价格、产品或促销的自定义限定符。自定义限定符键必须是唯一的。最多可以定义 20 个自定义限定符。

  7. 单击**“预览”**。

    现在，您可以使用要预览的上下文在网店中导航。

    为了便于共享，浏览器选项卡中的 URL 已更新为包含上下文值。

有时，您必须与预览的网店进行交互才能查看预期的行为。例如，您可以单击特定尺码的衣服以查看任何适用的折扣价格。

如果您遇到 Storefront Preview 的任何问题，您可以在 MRT 环境中启用 Storefront Preview 日志。 当您单击**“预览”**按钮时，这将打印额外的日志，以帮助您调试问题。

要启用 Storefront Preview 日志，请将 MRT 环境变量STOREFRONT_PREVIEW_DEBUG=1添加到您的 MRT 环境中。

您可以使用 MRT 结尾日志来读取 Storefront Preview 日志。

本节针对使用 Storefront Preview 时可能遇到的常见错误提供建议的解决方案。

根据您的浏览器，在未启用第三方 Cookie 时，您可能会遇到不同的行为。

  • **Chrome：**此时将显示一个模式，指出“此网店未启用预览”，并且网店显示 SecurityError。
  • **Safari 浏览器：**此时将显示一个模式，指出“无法初始化 Storefront Preview”，并且网店不可见。

**原因：**您的浏览器不允许使用 https://runtime.commercecloud.com 上的第三方 Cookie。

**建议的解决方案：**更新您的浏览器设置以及您可能用于允许第三方 Cookie 的任何扩展程序https://runtime.commercecloud.com。

加载 Storefront Preview 时出现错误消息："Preview is not enabled on this storefront!"

**原因：**网店缺少启用与 Runtime Admin 通信的脚本文件。

**建议的解决方案：**按照错误消息窗口中显示的说明进行操作，或完成步骤 4中的配置。

单击**“预览”**按钮时出现响应错误消息：

建议的解决方案： 完成步骤 1 和步骤 2中的配置。

根据您的浏览器，如果没有正确的内容安全政策，您可能会遇到错误。

  • **Chrome：**将显示一个模式，指出“此网店上未启用预览”，并且网店显示一个错误页面，指出“拒绝连接”。
  • **Safari 浏览器：**此时将显示一个模式，指出“此网店未启用预览”，并且网店不可见。

**原因：**您的网店在其内容安全政策中不允许使用 Runtime Admin。

**建议的解决方案：**按照步骤 5 中的说明正确配置内容安全政策。

Storefront Preview 加载的初始页面是配置为环境的外部主机名的域。

**原因：**未在环境设置中正确配置外部主机名。

建议的解决方案：在环境设置的高级部分中配置“外部主机名”以指向正确的域。

单击**“预览”**按钮时看到的响应错误消息：

**建议的解决方案：**完成第 3步。

单击**“预览”**按钮时看到的响应错误消息：

**原因：**MRT 环境变量 SLAS_PRIVATE_CLIENT_ID 中的值不正确和 SLAS_PRIVATE_CLIENT_SECRET /或错误的 SLAS 专用客户端配置。

**建议的解决方案：**完成第 1 步和第 2步。

在将 onContextChange 道具添加到 StorefrontPreview 组件后预览站点时，可能会收到错误消息或意外结果。

**原因：**道具调用的 onContextChange 函数可能存在问题。

**建议的解决方案：**从 StorefrontPreview 组件中删除 onContextChange 道具及其调用的函数。然后预览您的站点，看看是否出现相同的问题。如果没有，请调试函数以解决任何错误。例如，您能：

  • 将 onContextChange 道具及其回调的函数添加到 StorefrontPreview 组件。请参阅与第三方 CMS 集成。
  • 在预览站点时检查网络活动，并查看提取请求是否发送了预期的数据。

如果在删除 onContextChange 道具及其调用的函数后仍有问题，请打开支持案例。

预览站点时，内容未按预期显示，并且不会发生上述错误。例如，价格不会根据您在 Storefront Preview 中输入的值而更改。

**原因：**您可能没有完成一个或多个前提条件。

**建议的解决方案：**确认您已完成所有前提条件。如果您这样做了，但仍然遇到问题，请打开支持案例。