本周建议：先检查代码是否仍从响应顶层直接读取 vp_token。 自 2026 年 8 月起，Android 官方文档所列的新格式包含 protocol 和 data，vp_token 位于 data 内；2026 年 8 月后开始接入的应用应按新格式实现，迁移中的既有集成则按官方说明兼容新旧结构。客户端读出字段不等于凭证已验证，账号创建或登录前仍须由服务端完成密码学验证。（核实自 Android 官方邮箱验证实现指南。）
适合正在排查 Credential Manager 邮箱验证解析异常的 Android 开发者，以及评估新旧格式迁移方案的移动端负责人。
QA 可据此区分客户端解析、服务端验证和邮件验证码回退各自需要的验收证据。
最后更新于 2026 年 10 月 28 日；响应结构与迁移说明核实自 Android 官方实现指南及邮箱验证概览。
Android Digital Credentials API 邮箱验证响应格式测试：先定位读取层级
旧代码读取不到 vp_token，不一定意味着设备没有邮箱凭证。常见原因是解析器仍假定该字段位于响应顶层，而新响应把它嵌入 data；因此，遇到“顶层缺少 vp_token”时，不要直接把结果归类成“无可用凭证”，先记录脱敏后的实际外层键名，再依集成时间判断应读取哪种结构。官方示例明确展示了新格式中的 protocol、data 和嵌套 vp_token。(Android 官方实现指南)
需要特别区分两种 JSON：发给 Credential Manager 的 OpenID4VP 请求，与应用收到的凭证响应不是同一份对象。请求示例中的 requests、protocol、data 描述请求内容；响应读取则以官方“Parse the response”和原始响应示例为准，不能仅因请求也含有 data，就把请求的解析路径照搬到响应上。OpenID4VP 规范定义了凭证请求与呈现流程；Android 的实现指南进一步给出本场景的响应包装结构。
新版响应里的 vp_token 应从哪里取？ 对照 Android 邮箱验证实现指南的响应示例，先取外层 data，再在其中取 vp_token；之后才按请求中的凭证查询标识定位对应数组和凭证字符串。protocol 也应与 data 一同作为外层结构核对，而不是误当作 vp_token 的子字段。
{
"protocol": "openid4vp-v1-unsigned",
"data": {
"vp_token": {
"user_info_query": ["<凭证字符串>"]
}
}
}
这里的 user_info_query 是示例中与请求查询标识相对应的键，不应把它硬编码成所有请求都相同的固定值。解析器应使用自家请求中声明的标识来取值，并对字段不存在、类型不符或数组为空等情况作明确处理，而非把解析异常静默转换成“凭证无效”。
新接入与迁移中的解析策略
不同集成状态对应的处理方式不同。下表的优先级评分是我们的排障顺序建议，不是 Android 官方评级。
| 集成状态或故障表现 | 需要核对的结构 | 建议处理 | 排障优先级评分 |
|---|---|---|---|
| 2026 年 8 月后开始接入 | protocol 与 data.vp_token |
以新格式实现解析；不要依赖旧顶层路径 | ★★★★★ |
| 已有集成正在迁移 | 新格式与既有旧结构 | 按官方迁移说明兼容两种结构，并关注旧格式退出提示 | ★★★★★ |
顶层没有 vp_token |
实际返回的外层键及 data 内容 |
先判断是否为新格式，再决定是否属于字段缺失 | ★★★★☆ |
data 存在但凭证数组为空或类型异常 |
vp_token、查询标识及对应值类型 |
记录脱敏后的结构，分开处理空结果与 JSON 解析错误 | ★★★★☆ |
| 客户端读到邮箱字段，账号流程仍失败 | 服务端验证结果与应用状态 | 检查服务端验签、nonce 和业务状态，不以 UI 展示作为成功依据 | ★★★★★ |
旧的邮箱凭证解析代码为什么会读不到 vp_token？ 若代码直接调用顶层对象的 getJSONObject("vp_token")，而返回内容实际采用新包装结构，读取就会在错误层级失败。另一个容易忽略的情况是：客户端只解出了 data，却未按请求标识继续进入 vp_token 的对应值；此时字段“存在”仍不代表已拿到要提交给服务端的完整凭证。应逐层对照 Android 官方响应代码示例，而不是依据日志里是否出现字符串 vp_token 作结论。
新集成和迁移中的应用分别兼容什么？ 新接入项目按官方要求直接实现新格式；既有项目在迁移期按官方指引处理新旧响应，不能把兼容分支当成新应用的默认实现。官方文档说明旧格式处于逐步退出过程中，但没有在这份说明中给出可供所有项目套用的统一退出日期或版本范围，所以不要自行写入固定兼容版本；每次升级前应重新检查官方迁移提示。
服务端验签才是凭证验证边界
客户端解析的用途是取得原始响应，或为界面提供预览信息；它不能证明响应来自可信发行方，也不能证明凭证未被篡改或由当前持有者提交。Android 指南要求把完整响应和原始 nonce 交给服务端，在账号创建或登录前完成验证。按该指南，服务端需要核验发行方、SD-JWT 签名、凭证中的持有者绑定信息与 Key Binding 签名，并确认 nonce 与本次请求匹配。
Android 数字凭证安全说明也把发行方签名检查和持有者对 nonce 的签名检查作为不同的安全环节：前者用于核实凭证来源与完整性，后者用于证明提交者控制与凭证绑定的密钥，并降低重放风险。对工程实现来说，这意味着不能只检查 email 或 email_verified 是否存在，也不能只在客户端解码 SD-JWT 后就把账号置为已验证。
至少要留存哪些验收证据？ 在自家服务端测试日志中记录验证结论、失败所属阶段和 nonce 比对结果；凭证正文、邮箱、签名材料及访问令牌应按最小必要原则脱敏或避免写入普通日志。若要依据标准核查数据模型边界，可参考 W3C 可验证凭证数据模型；具体的 Android 邮箱响应解析与验签要求仍以 Android 实现指南为准。
邮件验证码回退的验收边界
Credential Manager 没有返回可用凭证、用户选择其他方式、响应异常或服务端验证失败时，注册流程应提供清晰的替代路径，而不是停留在无法继续的错误页。Android 官方建议保留“换一种方式”等入口；概览也说明，Credential Manager 邮箱验证适用范围有限，且凭证流程不等同于验证邮件是否能送达。对非 @gmail.com 地址，官方建议考虑额外挑战，以确认用户当前仍能访问该邮箱。(Android 邮箱验证概览)
邮件验证码回退测试不应把几个不同的结果合并成一个“通过”。我们在自家应用或获授权环境中，分别检查服务端是否发出邮件、测试收件端是否收到预期邮件，以及应用是否只有在验证码有效并通过服务端校验后才更新验证状态。收件端收到邮件只能证明这条测试路径收到了邮件，不能验证数字凭证的签名、发行方或持有者绑定。
可按下面的顺序完成回归，每一步都记录对应证据：
- 固定测试环境与用例。 只针对自家应用或获授权环境，分别准备新接入路径、迁移路径、无凭证路径和邮件回退路径；不要用第三方平台批量创建账号。
- 采集原始响应结构。 在测试构建中保存经过脱敏的外层键、字段类型与嵌套层级；避免把可识别个人身份的邮箱、完整 SD-JWT 或 nonce 写进共享日志。
- 跑新格式解析。 核对
protocol、data、data.vp_token、请求查询标识及对应凭证值；逐项模拟字段缺失、类型不符、空数组和非预期外层结构。 - 跑迁移兼容分支。 对既有集成分别输入官方示例所对应的新结构与旧结构，确认分支依据实际结构选择，且新接入路径没有悄悄退回旧路径。
- 验证服务端拒绝与通过。 将完整响应和原始 nonce 交给测试服务端；分别检查签名、发行方、持有者绑定或 nonce 验证失败时不会创建账号，验证成功时才进入后续账号流程。
- 单独验收邮件回退。 触发无凭证、异常响应或服务端拒绝场景，核对备用入口、邮件发送、受控收件和应用验证码校验状态；各步骤分别记结果，避免用“收到了邮件”代替端到端闭环结论。
- 复核结论与升级记录。 保存脱敏后的响应结构摘要、服务端验证结果、应用最终状态及文档复核日期；Android 格式或迁移说明更新时重新跑相关用例。
对照排查时，还要留意几个不属于 JSON 解析本身的限制：官方概览指出该能力面向 Android，且当前只支持消费者 Google 账号，不支持 Workspace 和受监管账号；设备离线或相关账号已移除时，流程可能无法提供凭证。成功取得凭证也不保证后续邮件能进收件箱，若产品需要确认用户当前可收取邮件，邮件验证码仍是另一条独立验证路径。
让测试收件只证明它能证明的事
对自家邮件回退流程，隔离测试收件箱可以帮助 QA 检查验证码邮件是否发出、内容是否符合预期，以及应用是否正确消费验证码；但它既不参与 Credential Manager 响应解析，也不能替服务端验证凭证真伪。若用临时地址做短期回归，先确认当前收件箱仍在有效状态，并避免把它绑定到需要长期找回的生产账号。FwdQuick 的临时收件箱页面说明其地址可即时用于短期收件且无需注册；隐私与清理边界可另查数据处理说明，不要把临时收件误当作长期账户恢复渠道。
因此，排障记录最好明确写成三项：客户端是否按预期读取到嵌套数据；服务端是否验证通过凭证及原始 nonce；邮件回退是否完成发送、收件与应用状态更新。这样的记录能避免把“解析成功”“邮件到达”和“凭证可信”混为一谈，也更便于在格式迁移后复现真实故障。
若当前任务只是测试自家应用的邮件验证码回退，使用 FwdQuick 临时收件箱可以把测试邮件与工作主邮箱分开；它是收件验证的辅助工具，不是数字凭证验证器，也不保证第三方邮件送达。若回归需要一封临时测试邮件，免注册、即开即用的收件方式比反复使用个人主邮箱更省事；若测试账号要长期保留、需要邮件找回或持续联系，则应改用长期可控的邮箱方案。