通过嵌入式结账集成，您可以将基于网络的结账流程嵌入到 Google 平台上。如果您的产品需要原生 API 无法支持的复杂逻辑（例如自定义），请使用此路径。您将实现一个结账界面，该界面将通过 iframe 嵌入到结账流程中。
什么是嵌入式结账？
嵌入式结账 (EC) 允许宿主（例如 Google 搜索或 AI 代理）在其应用内显示您现有的基于网络的结账流程（使用 iframe 或 WebView）。与标准网页重定向不同，这种方式允许双向通信。主机可以“委托”特定任务（例如选择已保存的地址或使用已存储的凭据付款），从而提供更快速、更原生的体验，而您仍然是记录在案的商家并负责处理实际的订单创建。
商家实施核对清单
如需支持嵌入式结账流程，您必须在 UCP API 和前端结账应用中实现以下要求。
1. 启用发现功能 (UCP API)
您必须在 UCP API 响应中声明结账流程支持嵌入式扩展服务。
- 操作：将
dev.ucp.shopping.embedded_checkout功能对象添加到 UCP 响应功能数组。 - 要求：添加规范和架构网址。
- 可选：如果您需要身份验证（例如 JWT 令牌）才能加载结账流程，请将
auth.required设置为 true。
"capabilities": [
{
"name": "dev.ucp.shopping.embedded_checkout",
"version": "2026-01-11",
"spec": "https://ucp.dev/specs/shopping/embedded_checkout",
"config": {
"auth": { "required": true }
}
}
]
2. 处理网址初始化（前端）
当宿主加载 continue_url 时，会附加特定的查询参数。前端必须在加载后立即解析这些数据。
- 操作：解析以下网址查询参数：
ec_version：协议版本（例如，2026-01-11）。ec_auth：（如果适用）验证主机提供的身份验证令牌（如果您设置了auth.required: true）。ec_delegate：主机希望以原生方式处理的操作的英文逗号分隔列表（例如，payment.credential、fulfillment.address_change、payment.instruments_change）。
3. 建立通信（前端）
通信使用 postMessage，采用 JSON-RPC 2.0 格式。
- 操作：为
message事件实现监听器。 - 要求：您必须验证每条消息的来源，以确保其与主机匹配。
- 原生支持：对于原生应用主机，请检查并利用注入的全局变量（例如
window.EmbeddedCheckoutProtocolConsumer）如果postMessage不可用。
4. 执行握手（前端）
结账界面呈现后，您必须告知宿主您已准备就绪，并确认您接受哪些委托。
- 操作：加载后立即发送
ec.ready请求。 - 载荷：包含一个
delegate数组，其中列出了您同意让主机处理的功能。 - 示例：如果请求的网址为
ec_delegate=payment.credential，并且您接受，请在ec.ready载荷中添加"payment.credential"。
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
"jsonrpc": "2.0",
"id": "ready_1",
"method": "ec.ready",
"params": {
"delegate": ["payment.credential"] // List capabilities you accept to delegate
}
}), "*");
5. 实现委托逻辑（前端）
如果您在握手过程中接受了委托，则必须修改界面行为，以避免冲突。
- 操作：隐藏委托任务的相关界面元素。
- 示例：如果
fulfillment.address_change已委托，则隐藏地址表单，并改为显示“更改地址”按钮。 - 操作：当用户点击该按钮时，发送
_request消息（例如，ec.fulfillment.address_change_request）发送到主机。 - 操作：等待主持人的回应。响应将包含新数据（例如，所选地址）。
- 要求：根据主机返回的数据，使用 PUT 样式的替换（替换整个对象部分）来更新结账状态。
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
"jsonrpc": "2.0",
"id": "req_1",
"method": "ec.payment.credential_request",
"params": {
"checkout": currentCheckoutState // Pass the full current checkout object
}
}), "*");
6. 发送生命周期和状态更新（前端）
您必须让宿主了解结账状态，以便他们更新界面或处理错误。
- 操作：在状态发生变化时发送通知（不含 ID 的消息）：
ec.start：结账界面完全可见时。ec.line_items.change：购物车内容或总金额是否更新。ec.buyer.change：买家详细信息是否更新。ec.complete：订单成功提交的时间。ec.error：如果发生严重错误。
7. 强制执行安全措施（服务器/标头）
您必须确保结账流程不会被恶意方嵌入。
- 操作：实现内容安全政策 (CSP) 标头。
- 要求：将
frame-ancestors <host_origin>;设置为仅允许受信任的主机进行嵌入。 - 导航：将用户从结账流程中引导出去的块逻辑（例如，移除指向首页的“继续购物”链接）。 3DS 验证或第三方付款重定向可不受此限制。