使用混合身份验证配置混合网店

在 B2C Commerce 版本 25.3 中，混合身份验证（auth）取代了插件 SLAS 插件选项。

混合身份验证是一种独立解决方案，适用于需要Storefront Reference Architecture （SFRA）/SiteGenesis （SG）授权和Shopper Login and API Access Service （SLAS）授权的站点实施。这意味着您需要 dwsid （SFRA/Site Genesis）和 JSON Web 令牌（SLAS），并且这些令牌必须保持同步。混合身份验证是对插件 SLAS 方法的改进，提供了一种更高效、更简化的方法。

Hybrid Auth 通过将功能直接移入 B2C Commerce 平台，提高了混合网店的性能和稳定性。

我们强烈建议迁移到混合身份验证，以便您可以利用改进的性能和简化的工作流程。

Note

本指南介绍如何为混合网店配置混合身份验证，该网店既是 SFRA/SiteGenesis 的一部分，又是可组合网店。

有关混合身份验证的详细信息，请参阅混合身份验证。

流程摘要

使用混合身份验证的混合实施涉及的任务包括：

完成混合身份验证中的步骤。
为可组合网店配置混合身份验证（必需）。
使用 Commerce API CDN 区域将流量路由到 Managed Runtime。请参阅用于分阶段无标头部署的 CDN API （必需）。
使用 Einstein Activities 进行分阶段无头部署（可选）以获取分析

前提条件

若要使用混合身份验证，请使用以下命令构建站点：

commerce-sdk-react@3.3.0 或更高版本
Progressive Web App （PWA）工具包版本 3.10 或更高版本

混合身份验证功能支持矩阵

下表比较了插件 SLAS 与混合身份验证的 PWA Kit 功能支持。

PWA Kit 中支持的功能名称	PWA Kit 中支持的插件 SLAS	。混合身份验证	说明
SiteGenesis	N	Y
第三方 IDP 和社交登录	N	自 2025 年 4 月 30 日起部分支持。	第三方 IDP：与第三方 IDP 的所有交互都必须使用 SLAS 完成。如果您当前在 B2C Commerce 中使用购物者身份验证，并且已在 Business Manager 中配置了 OAuth2 提供程序，则必须在 SFRA/SiteGenesis 应用程序中进行调整并更改 UI 工作流程和身份验证。使用 SLAS 身份提供商并更改任何购物者登录屏幕以与 SLAS 交互。社交登录：这与第三方 IDP 支持相同，但与上一段中描述的警告相同：登录必须通过 SLAS。
无密码登录	N	Y
SLAS 私人客户	Y	Y
SLAS 公共客户端	Y	N*	混合身份验证支持计划在将来的版本中发布。
SLAS 可信系统（TSOB）	N	Y
Script API “记住我”功能	不	适用传统的记住我功能通过 SLAS 得到增强，延长了到期时间，并且在迁移到 HA 时是多余的。	重要提示：如果要迁移到 HA，并且您的实现在调用 loginCustomer 时为 rememberMe 设置了布尔标志，则当前使用的结果 `dwcustomer_*` cookie 存在问题。Salesforce 目前建议，如果正在使用此功能，则不要实施混合身份验证。 `rememberMe`HA 持久登录增强了功能。 B2C Commerce 版本 25.6 中提供了从 rememberMe 过渡到混合身份验证持久登录的支持。在这种情况下，应等到 25.6 版本后再迁移到 HA。
PWA Kit 版本 2.x	Y	N*	对于 HA，对 PWA Kit 2.x 的支持依赖于 SLAS 公共客户端支持，并计划在将来的版本中发布。
PWA Kit 版本 3.x	Y Y	`salesforce/commerce-sdk-react`	v3.2.0 随 PWA Kit 3.9.0 一起打包。
请勿跟踪（DNT）	N	Y	您必须执行特定步骤来启用和同步 DNT。请参阅文档指南。
购物者上下文	N	Y	Salesforce 建议您启用购物者上下文进行混合身份验证，因为这是为 API 提供个性化数据的唯一方式。请参阅 Shopper Context 文档。基于地理位置的个性化需要在 Shopper Context 和 SFRA/SiteGenesis 之间同步。请参阅文档指南。注意：在 B2C Commerce 版本 25.5 中，Shopper Context 的 Script API 可用于基于地理位置的个性化。
控制器排除	Y	N	在混合身份验证中，无需排除任何控制器。
Cookie 设置自定义	Y，通过自定义	N/A	在混合身份验证中，与不同 plugin_SLAS ，您不再有权访问 cookie 对象，也无法再覆盖 cookie 设置。

*计划在将来的版本中提供支持。

为可组合网店配置混合身份验证

要为属于 SFRA/SiteGenesis 和可组合网店的混合网店配置混合身份验证，请按照本指南中详细描述的这些步骤进行作。

设置嵌入式内容交付网络（eCDN）源规则。
创建 PWA Kit Retail React App。
更新 PWA Kit 路由。
升级 @salesforce/commerce-sdk-react。
在托管运行时启用 Cookie。
从插件路径中删除插件 SLAS。
启用/禁用不跟踪同步。

设置嵌入式内容交付网络（eCDN）源规则

配置嵌入式内容交付网络（eCDN）以将漏斗顶部的页面请求发送到可组合网店：主页（/）、分类列表页面（/category）和产品详细信息页面（/product）。这些页面部署到在 mystorefront.mobify-storefront.com 上运行的托管运行时（MRT）环境。当购物者决定进行购买时，eCDN 会将购物者重定向到运行在上 www.mystorefront.com运行的现有 SFRA/SG 结账页面。

要使用 Commerce API CDN 区域将流量路由到托管运行时，请按照混合实施的 CDN API 中的步骤作。

有关将流量路由到 MRT 的更多信息，请参阅：

创建 PWA Kit Retail React App

执行 1 或 2。

使用 SLAS 专用客户端配置创建 Retail React App
- 通过在终端窗口中运行以下生成器命令来创建 PWA Kit 应用： npx @salesforce/pwa-kit-create-app my-hybrid-storefront
- 选择 使用您自己的 Commerce Cloud 实例的零售应用程序。
- 按照终端中的说明进行作。
- 当被问到 时回答 是 您的 SLAS 客户端是私有的吗？

或

或者，可以使用预设配置生成 Retail React App，并在生成应用后将 SLAS 客户端 ID 更改为专用客户端。
- 按照快速入门中的步骤作。
- 使用 SLAS 专用客户端
- 确保用于混合身份验证的 SLAS 客户端包含范围 sfcc.session_bridge 。

更新 PWA Kit 路由

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

如果 PWA Kit 项目是使用模板扩展性使用 Retail React App 模板版本 3.x 生成的，则可以重写该 overrides/app/routes.jsx 文件以使用 JavaScript 筛选出指向非 PWA Kit 页面的链接。

我们创建了一个 overrides/app/routes.jsx 文件的示例覆盖，其中包含所有更改以过滤掉 /cart 和 /checkout 路由。自定义此公共 gist 中的示例重写代码，以筛选出指向非 PWA Kit 页面的链接。
最后，更新 app/routes.jsx 中的 PWA 全面涵盖路由 (/*)。将 PWA <PageNotFound /> 组件替换为到默认源的重定向。

1import {withRouter} from 'react-router-dom'
2    ...
3    {
4        path: '*',
5        component: withRouter((props) => {
6            const {location} = props
7            const urlParams = new URLSearchParams(location.search)
8
9            useEffect(() => {
10                const newURL = new URL(window.location)
11                if (!urlParams.has('redirected')) {
12                    newURL.searchParams.append('redirected', '1')
13                    window.location.href = newURL
14                }
15
16            }, [window.location.href])
17            if (urlParams.has('redirected')) {
18                return <PageNotFound {...props} />
19            }
20            return null
21        })
22    }

升级 @salesforce/commerce-sdk-react

如果您的站点使用 commerce-sdk-react，请升级到 @salesforce/commerce-sdk-react@3.2.0 或更高版本。

在托管运行时启用 Cookie

启用混合身份验证后，SLAS /oauth2/token 请求包含使用 Set-Cookie 响应中的标头桥接 dwsid 的会话。

在托管运行时中，启用 Cookie 直通：

登录到 Managed Runtime Admin。
导航到您的项目和环境。
单击环境设置。
滚动到“ 高级 ”部分，然后选择 “编辑 ”按钮。
启用 Cookie 旁边的 ****开关。
向后滚动到“ 高级”部分，然后选择 “更新 ****”。
等待网店套装重新部署。

从插件路径中删除插件 SLAS

仅当您以前在混合网店中使用过插件 SLAS 时，这些步骤才适用。如果您有新的混合网店，并且以前从未使用过插件 SLAS，则可以跳过这些步骤。

Note

迁移到 B2C Commerce 混合身份验证后，PWA Kit 不再使用插件 SLAS。要从混合网店中删除插件 SLAS，请执行以下作：

前往 管理 > 站点 > 管理站点 > 选择站点。
转到 “设置 ”选项卡。
从插件路径中删除插件 SLAS。
如果您有任何关于购物者身份验证的代码自定义，但不是特定于插件 SLAS，它们应继续按原样工作。
- 如果您进行了任何特定于插件 SLAS 的自定义，请查看这些自定义。这些更改可能不是必需的，或者您可能需要在其他插件中重新实施更改。
- 遵循最佳实践。所有代码自定义都必须在单独的插件中实现，而不是直接在开箱即用的 SFRA 插件代码中实现。
- 确保在切换到混合身份验证时，任何自定义插件代码都不会调用会话桥接端点。这将导致购物者会话出现问题。混合身份验证现在为您处理购物者会话。

启用/禁用不跟踪同步

对于仅限 SFRA 的站点，当为购物者登录扩展启用混合身份验证时，DNT 值会自动同步到扩展会话，从而确保跨会话的无缝体验。

要在 Business Manager 中启用/禁用不跟踪（DNT）同步，请导航到 商家工具 > ，选择站点 > 站点首选项 > 混合身份验证设置。

当您同时启用混合身份验证和 DNT 同步时，一个站点上的购物者提供的跟踪同意将自动与另一个站点同步。例如，在主页在 PWA Kit 上运行，购物车页面在 SFRA 上运行的混合站点中：

在主页（PWA Kit）上，购物者会看到一份同意书，并提供其跟踪首选项。
当购物者导航到购物车页面（SFRA）时，PWA Kit 中的 DNT 值将与 SFRA 同步。
因此，SFRA 购物车页面不会再次提示购物者进行跟踪同意。

DNT 定制

如果您已经自定义或计划自定义默认 DNT 实现，则可能不需要默认同步，也无法按预期工作。在这种情况下，您可以使用站点首选项禁用 DNT 同步。即使关闭了 DNT 同步，您仍然可以启用混合身份验证。

DNT Cookie 过期

SFRA 和 PWA Kit 之间的 DNT cookie 过期有一个关键区别：

SFRA 将 DNT Cookie 设置为在会话结束时过期。
PWA Kit 设置到期时间以匹配刷新令牌的有效期（例如，访客购物者为 30 天）。

当购物者从 PWA Kit 页面移动到 SFRA 页面时，DNT cookie 的过期时间将从刷新令牌的过期时间更改为基于会话的过期时间。如果购物者关闭浏览器，则 Cookie 将被删除。因此，当购物者返回时，跟踪同意横幅将按预期再次显示。

在本地设置混合（SIG 实例）

我们强烈建议在本地环境中测试混合设置。为此，您必须设置反向代理，因为 eCDN 不支持 SIG 和 ODS。要在 SIG 实例上本地设置和测试混合站点，您必须使用自己的反向代理或 CDN 来拆分流量。

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

配置按 On-Demand Sandbox 以使用别名

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

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

配置 PWA Kit 路由以为传出 URL 添加前缀（可选）

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

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

1import {withRouter} from 'react-router-dom'
2// extensible
3import useMultiSite from '@salesforce/retail-react-app/app/hooks/use-multi-site';
4// non-extensible
5import useMultiSite from './hooks/use-multi-site';
6
7const DEFAULT_SITE_ID = 'RefArch'
8...
9 {
10    path: '*',
11    component: withRouter((props) => {
12        const {location} = props
13        const urlParams = new URLSearchParams(location.search)
14        const {site} = useMultiSite()
15        const siteId = site && site.id ? site.id : DEFAULT_SITE_ID
16        useEffect(() => {
17            const newURL = new URL(window.location)
18            if (!urlParams.has('redirected')) {
19                newURL.searchParams.append('redirected', '1')
20                newURL.pathname = `/s/${siteId}/${window.location.pathname
21                    .split('/')
22                    .slice(2)
23                    .join('/')}`
24                window.location.replace(newURL)
25            }
26        }, [window.location.href])
27        if (urlParams.has('redirected')) {
28            return <PageNotFound {...props} />
29        }
30        return null
31    })
32}