分阶段无头部署

Storefront Reference Architecture (SFRA) 和 SiteGenesis 的用户现在可以分阶段部署无头技术。例如，可以使用 PWA Kit 为产品页面部署大胆的新体验，并将结帐流程保持在 SFRA 上，直到无头转换的下一阶段。这种分阶段方法可以帮助您更快启动，并最大限度地减少无头操作过程中的干扰。

本指南介绍如何使用会话桥接和路由规则，以使 PWA Kit 能够支持一组页面而 SFRA 支持另一组页面，并提供无缝的用户体验。

要了解有关在分阶段无头上下文中使用 Einstein Activities 的更多信息，请参阅用于分阶段无头部署的 Einstein Activities。

要使购物者能够在由不同网店架构支持的页面之间无缝导航，需要使用一种称为会话桥接的技术。会话桥接使用 cookie 在不同系统之间共享购物者刷新令牌和会话令牌。

解锁会话桥接的关键是 Shopper Login and API Access Service (SLAS)，这是一种新的基于标准的身份验证和授权解决方案，可通过 HTTP 请求访问。SLAS 的购物者身份验证基于 OpenID Connect，Commerce Cloud 的购物者 API 授权基于 OAuth 2。

当购物者浏览无头网店时，您使用 SLAS 请求访问令牌和刷新令牌，并将它们作为 cookie 存储在购物者的浏览器上。您可以使用 HTTP set-cookie 标头或客户端 JavaScript 设置 cookie。如果购物者从 SFRA 页面转换到 PWA Kit 页面（反之亦然），带有刷新令牌的 cookie 与 HTTP 请求一起发送，网店代码可以使用刷新令牌来登录用户。

Plugin SLAS 管理 B2C Commerce 会话（与 dwsid 关联）以及 SLAS 会话（与 access_token 关联）。会话桥接链接 dwsid 和 access_token 到同一购物者会话。

Plugin SLAS 使用 2 种会话桥接方法：

1. SLAS 会话桥（API: getSessionBridgeAccessToken）
   • 由 Plugin SLAS 仅用于新访客登录。
   • 会话桥接后不会生成新的 dwsid，因此网店不会要求重新渲染，并且可以发送 200 OK 响应。
2. OCAPI 会话桥 (API:获得 OCAPI 会话)
   • 由 Plugin SLAS 用于注册购物者登录和刷新令牌登录。
   • 在会话桥接后生成新的 dwsid，因此网店需要刷新并且必须发送 302 重定向响应。

创建分阶段无头部署的第一步是设置您的 PWA Kit 应用程序以使用 SLAS（如果您还没有）。按照我们的设置 API 访问指南中的说明进行操作。

要启用 SFRA 的分阶段无头部署，您必须安装 Plugin SLAS 插件。插件的自述文件中提供了完整的安装说明。

SLAS 插件用户重要注意事项

Plugin SLAS 插件多次调用各种 API，这可能会影响网店性能。在将插件添加到生产环境 (Production) 网店之前，请比较使用和不使用插件的网店性能，以确定它是否适合您。

插件还可以根据以下条件引入重定向：

• 当购物者还没有会话 cookie 时
• 当购物者的会话 cookie 过期时
• 当搜索引擎索引您的网站时

目前，该插件仅取代直接登录凭据存储在 Salesforce 中的 B2C Commerce 系统。

当与愿望清单插件一起使用时，在登录成为注册用户时不会转移访客愿望清单。

在使用插件之前，请查看 GitHub 上的问题页面。

由于 Plugin SLAS 插件是为 SFRA 而设计，因此必须编写额外的代码才能将其与 SiteGenesis 一起使用。SiteGenesis 实施可以在购物者身份验证和授权流程的各个点利用插件中的代码。

因为该插件使用 B2C Commerce Web 服务框架来处理 SLAS API 调用，所以 SiteGenesis 实施可以向插件实现的 Web 服务发出请求。这些 Web 服务包括访客登录、注册客户登录、令牌刷新、注销和合并访客篮。插件还实现合并 API 会话和网店会话的服务。

SiteGenesis 实施还可以使用自定义挂钩 (app.plugin.slas.login) 来实现使用 SLAS 的访客和注册用户的登录。检查 dw.system.request.onSession 中的插件 onSession 挂钩的自定义代码，了解它如何用 SLAS 替换脚本 API 以进行购物者登录。

要使用 PWA Kit 实现会话桥接，您必须在 commerce-api/auth.js 中修改处理 API 授权的代码以使用 cookie 而不是本地存储。

如果您的 PWA Kit 项目是使用 2.7.x 版本的 Retail React App 模板生成的，则可在 auth.js 中取消注释这行代码，并切换至 CookieStorage 以储存令牌。这是管理 SFRA 和 PWA Kit 站点之间会话的必需条件。

您还必须修改购物者登录后调用会话桥 API 的 commerce-api/auth.js 中的代码。为此，您必须取消 auth.js 中这行代码的注释。

为了节省您的时间，我们创建了包含所有更改的文件的替代版本，并通过公共 gist在 GitHub 上提供。

如果您的 PWA Kit 项目是通过 3.0.0 或更高版本 Retail React App 模板生成的，则默认启用上述更改，无需进一步更改代码。

授权流程从刷新令牌开始。如果刷新令牌 cookie 可用，PWA Kit 应用程序会将刷新令牌交换为访问令牌。否则，应用程序将启动授权代码授予流程，如 OAuth 2.1 标准所定义。它还遵循代码交换证明密钥 (PKCE) 流程。

当 SLAS 授予新的访问令牌和新的刷新令牌时，应用程序会将它们存储在 cookie 中。然后应用程序向 OCAPI 的创建会话端点 (/session) 发出 POST 请求。此端点创建由 SFRA 使用的会话。应用程序将会话令牌存储在 cookie 中。

PWA Kit 应用程序创建的 Cookie：

• cc-nx-g - SLAS 访客购物者刷新令牌
• cc-nx - SLAS 已注册购物者刷新令牌
• token - SLAS 访问令牌
• dwsid - Demandware 会话 ID

为了确保分阶段部署期间的无缝用户体验，您需要一种将流量路由到两个不同来源的方法：Managed Runtime 环境和 B2C Commerce 实例。此流量路由可以由内容分发网络 (CDN) 处理。

想象以下场景：

您有一个在 www.mystorefront.com 上运行的现有 SFRA 网店。您知道无头架构的优势，并希望利用 PWA Kit 来提供高性能和具有吸引力的体验。同时，您希望最大限度地降低进度风险，因此您选择分阶段的方法来部署 PWA Kit 网店。

您要将 CDN 配置为将隧道顶部的页面请求发送到 PWA Kit：主页 (/)、类别列表页面 (/category) 和产品详细信息页面 (/product)。这些 PWA Kit 页面部署到在 mystorefront.mobify-storefront.com 上运行的 Managed Runtime 环境。当购物者决定购买时，CDN 将购物者重定向到在 www.mystorefront.com 上运行的现有 SFRA 结帐页面。

要处理流量路由，您可以选择 Salesforce 的嵌入式 CDN (eCDN) 解决方案（由 Cloudflare 提供支持）或选择其他供应商的 CDN。

要使用 eCDN 将流量路由到 Managed Runtime，请使用 Commerce API 端点 createMrtRules。

API 支持使用 Cloudflare 规则表达式 将流量路由到 Managed Runtime 。它支持规则语言中可用字段的子集。支持以下字段：

• http.host 以匹配主机名
• http.request.uri.path 与请求路径匹配
• http.request.uri 与请求路径和查询字符串匹配
• http.cookie 与 cookie 匹配

您可以在代理区域上为每个实例请求 100 条单独规则，并在旧区域上的开发/生产实例之间共享总共 100 条单独规则。

• eCDN 仅适用于生产环境 (Production) 和开发环境 (Development) 实例，不适用于 Sandbox 或 ODS 实例。
• 必须使用 eCDN API 将准备环境 (Staging) 实例加入到 eCDN。有关更多信息，请参阅 B2C Commerce 信息中心上的 配置准备环境 (Staging) 的 eCDN 以及来自 Rhino Inquisitor 博客的 这篇文章。
• eCDN 不支持基于地理位置的路由。

为了帮助设计您的起源规则，请收集 PWA Kit 页面的完整路由列表。对于基于 Retail React App 模板的 PWA Kit 项目，路由在 app/routes.jsx 中列出。因为 PWA Kit 的服务器端渲染系统使用代理和静态资产的内部路由，所以还必须在路由规则中包含 /mobify/*。

对于我们的示例场景，必须在您的 CDN 中配置以下路由：

构建一个起源规则，其中包含列表中的所有 PWA Kit 路由，以将请求转发到 Managed Runtime 环境（示例场景内的 mystorefront.mobify-storefront.com）。

下图显示了我们之前描述的示例场景的 eCDN 配置：

默认情况下，PWA Kit 项目的 Retail React App 模板具有与 SFRA 不同的 URL 路由模式。例如，Retail React App 中产品详细信息页面的 URL 路径是 /products/{productId}.对于 SFRA，模式是 /{categoryId}/{productId}.

我们建议您更改 PWA Kit 网店中的路由模式以匹配您的 SFRA 站点。如果您无法匹配特定页面的 URL 模式（例如当分类 ID 在 URL 中不可用时的产品列表页面），您可以使用重定向插件 设置缩小差距的重定向。插件的自述文件中提供了完整的安装说明。

要完成分阶段无头部署的设置过程，您必须对 PWA Kit 项目进行更多更改。

默认情况下，PWA Kit 使用历史 API 进行导航。当购物者点击使用 React Router 的 <Link> 组件创建的链接时，它会触发软导航到与 app/routes.jsx 定义的路由对象路径匹配的组件。要链接到非 PWA Kit 页面（例如，由 SFRA 提供支持的页面），您必须从 app/routes.jsx 删除与 URL 路径名匹配的任何路由。

例如，如果您的 PWA Kit 项目是使用2.7.x 版 或 3.x 版 Retail React App 模板生成的，并且没有使用可扩展性：从路由数组中删除结账。

如果您的 PWA Kit 项目是通过使用可扩展性的 3.x 版 Retail React App 模板生成的，则可以覆盖 overrides/app/routes.jsx 文件以使用 JavaScript 过滤掉指向非 PWA Kit 页面的链接。 我们创建了一个 overrides/app/routes.jsx 文件的示例覆盖，其中包含所有用于过滤掉 /cart 和 /checkout 路由的更改，并通过公共 gist 在 GitHub 上提供。

最后，更新 app/routes.jsx 中的 PWA 全面涵盖路由 (/*)。将 PWA <PageNotFound /> 组件替换为到默认源的重定向。

对于 PIG 实例，客户可以使用 eCDN 在 SFRA（或 SG）和 MRT 源之间“拆分”流量。但是，eCDN 不支持 SIG 实例和 ODS。要在 SIG 实例上本地设置和测试分阶段部署站点，客户必须使用自己的反向代理或 CDN 来分割流量。

我们创建了一个示例 Node.js 应用程序，可用于开发和测试跨 PWA Kit 和 SFRA/SiteGenesis 的混合部署购物流程。 存储库的README中提到了设置反向代理的设置和配置说明。

我们制作了一个演示视频，介绍 SIG 实例上设置分阶段部署的步骤：

您可以将 ODS 配置为使用与生产环境 (Production) 配置类似的别名配置，这有助于保持本地和生产设置相同。例如，通过配置沙盒 (Sandbox)，使混合站点适用于 / URI，确保 pwa-kit 发送的 URL 不需要转换为包含站点 ID。这通常是生产环境 (Production) 站点的配置方式。

要在 Business Manager 中启用别名，请按照 Trailhead 上 Salesforce B2C Commerce 主机名别名 的本模块的说明进行操作。

您可以将 PWA Kit 路由设置配置成为所有传出 URL（例如，用于 SFRA 的 URL）添加前缀以包含 /s/SiteID 前缀。这可确保您的实例以 Sandbox 上通常使用的方式接收控制器 URL，而无需显式配置主机名别名。请注意，这可能不适合生产环境 (Production) 配置，因此您可能希望为生产环境 (Production) 与 Sandbox 部署采用不同的综合路线。

要配置路由前缀，请更新 app/routes.jsx 或 overrides/app/routes.jsx 中的 PWA catch-all 路由 (/*)。