先确认你测试的是 App Store Connect 配置式消息还是实时 Retention Messaging，再依次检查消息状态、订阅关联和 Sandbox 取消流程；Sandbox 测试者能看到最新草稿，未获批准不必然等于无法显示。如果走实时 API，还要核对服务端响应及回退配置。
- iOS 订阅开发者：在 Sandbox 取消订阅时看不到文案、图片或优惠，需要区分后台预览与系统取消流程。
- StoreKit 或服务端工程师：要确认测试账户、订阅标识、优惠资格及实时响应彼此匹配。
- CI 与发布负责人：要拆分判断环境构建、Sandbox 验收和上线前 API 性能测试各自验证什么。
时间安排：截至 2026 年 11 月 8 日，今天先确定消息路径并核对后台配置；本周完成一次系统订阅页取消复测，若使用实时 API，再查看请求、响应与回退日志。Retention Messages 于 2026 年 11 月 4 日正式发布。最后更新于 2026 年 11 月 8 日，信息核实自 Apple 的发布说明、配置指南、消息状态说明、Sandbox 取消测试说明及 WWDC26 官方演示。
先分流：后台配置式消息，还是实时 API 选消息？
这两条路径看起来都叫 Retention Messaging，但决策和故障证据不同。App Store Connect 配置式消息由已配置的消息、订阅与优惠规则决定展示内容；实时路径则由 App Store 发起服务端请求，你的端点返回选择。先认清路径，避免去查一条根本没有参与本次展示的链路。Apple 在 WWDC26 官方演示中说明了两种机制及实时请求失败后的回退关系。
| 你正在验证的路径 | 消息由谁决定 | 优先检查的证据 | 适合的排查方向 |
|---|---|---|---|
| App Store Connect 配置式 | App Store 按后台消息及适用规则展示 | 消息状态、订阅关联、账户资格、取消流程 | 先看预览，再做 Sandbox 系统取消 |
| 实时 Retention Messaging API | 你的服务端针对请求返回消息选择 | 请求是否到达、响应是否有效、消息标识及订阅是否匹配 | 同时确认后台消息与 API 默认消息可供回退 |
App Store Connect API 4.6 是一条相关但不同的版本线索：Apple 的发布记录标注其发布日为 2026 年 11 月 4 日。不要仅凭版本号推断实时端点已接入、已获 API 访问权限，或本次取消请求成功；它不能代替服务器收到请求和返回有效响应的证据。
Sandbox 中未审核的草稿也能测，状态仍要逐项核对
未通过 App Review 的 Retention Message 可以在 Sandbox 中测试。Apple 明确说明，Sandbox 测试者会看到最新草稿，不论它当前处于什么审核状态；生产环境则不同，已上线版本会继续展示，直到新草稿获批后才替换。因此，看到“准备提交”“等待审核”或“审核中”，不能单独作为 Sandbox 不显示的解释。状态含义可对照 Apple 的消息状态说明。
实际操作时，先在 App Store Connect 中记录消息当前状态，再确认自己最近保存的是哪一版；如果你编辑过已批准的消息，Sandbox 可能显示最新未发布草稿，而生产订阅者仍看到旧的已批准版本。若状态为“已拒绝”，查看审核反馈并修正内容；这仍不改变 Sandbox 测试者看到最新草稿的规则，但内容或关联配置需要重新核验。
接着检查订阅与优惠的关系。App Store Connect 中，一条消息可关联多个订阅，但一个订阅同一时间只能有一条有效的留存消息；优惠也必须关联到对应订阅和消息，用户还要符合优惠资格。Apple 的配置指南还说明，符合条件的订阅者会看到优惠，而不是图片；不符合优惠资格的人可能看到图片，或只看到文本。因此，“文案出现但优惠不出现”通常应先查资格和关联，不要直接判定消息整体失效。
- ✅ 无优惠消息：在预览中选择对应订阅，并将优惠设为无，核对纯文案或文案加图片的样式。
- ⚠️ 含优惠消息：分别预览有优惠和无优惠的情况，再检查测试账户是否满足订阅时长、优惠等待期及可用地区等条件。
- ❌ 只核对消息名称：名称用于后台管理，不能证明当前测试的产品标识已关联到这条消息。
为什么取消时仍没有消息？从测试账号和系统入口查起
预览正常只证明后台配置能生成预览，不代表测试账户已经走到真实取消场景。先确认测试设备使用的是预期的 Sandbox Apple Account，且购买订阅和发起取消的是同一账户、同一测试环境、同一自动续订订阅。若在本地用 StoreKit 配置文件做模拟，它适合验证应用内购买逻辑，但不能单凭本地模拟结果验收 App Store 的系统取消页。
然后从系统提供的订阅管理入口触发取消，而不是只点应用里自制的“取消订阅”按钮。Apple 的关闭自动续订测试步骤要求先为 Sandbox 账户购买自动续订订阅，再到设备的开发者设置中打开 Sandbox 账户管理页，选择对应订阅并执行取消。对 Retention Messaging 的展示验收，关键是让系统进入订阅取消流程；应用内按钮可以引导用户前往管理页，却不能替代该流程本身。
提醒：核对订阅产品标识时，不要只看应用显示名称。一个测试账户可能购买了同一订阅组内的另一档产品，导致你以为验证的是已关联消息的订阅，实际却没有命中对应规则。
如果你还在检查本地构建，先把“应用能否正确签名、安装并发起 Sandbox 购买”与“系统取消页是否显示消息”拆成两项。前者属于构建和 StoreKit 测试，后者还依赖 App Store Connect 配置、Sandbox 账户状态及系统取消入口；重建整个 Xcode 环境不能修复订阅关联或资格条件。
实时 API 未返回有效选择时，按回退顺序定位
使用实时 Retention Messaging API 时，先确认团队确实启用了这条路径；Apple 说明该 API 访问需要申请。再检查服务端收到的请求是否对应本次测试，核对原始交易标识、目标订阅、请求标识和本地化选择，并确认响应中的消息标识、产品或优惠签名与已配置资源一致。可用 Apple 的Retention Messaging API 文档核对接口对象和配置项。
响应缺失、超时或格式无效时，不应直接预期用户一定看到某条实时消息。Apple 的 WWDC26 演示描述了回退优先级：先尝试 App Store Connect 中为相应订阅配置的消息及适用优惠；没有对应配置时，再使用 Retention Messaging API 设置的默认消息。你需要分别记录三种情况：请求成功并返回有效选择、服务端未及时响应、响应无法解析。只记录“取消页没显示”会把完全不同的故障混成一个症状。
上线准备还多一道服务端性能门槛。Apple 的发起性能测试文档指出，Sandbox 性能测试需要先配置 Get Retention Message 端点；Apple 说明典型响应时间约为 700 毫秒，精确门槛以测试响应中的 responseTimeThreshold 为准，生产环境启用实时功能前需要通过测试。该数值是服务端响应要求，不是 Mac 或 Xcode 的编译性能指标。收到 429 等错误时，也应记录响应码并按 API 限流说明处理，而不是把它误判为订阅消息内容错误。
按复现点逐层复测，而不是重建整套环境
按下面顺序走一遍，复现在哪一步首次偏离预期，就回到那一层修正。每次测试尽量只改变一个条件，并保留测试账户、产品标识、消息状态和时间点，方便 CI 与发布负责人复核。
- 选定路径。记录本次只测 App Store Connect 配置式消息，还是实时 API；同时确认 API 访问状态，避免把两条路径的日志混看。
- 先做后台预览。检查文本、图片、订阅和优惠关联；对含优惠的消息，分别预览有资格与无资格的呈现。
- 确认消息版本与状态。记录最新草稿、已批准版本及当前审核状态；Sandbox 展示最新草稿，不要拿生产版本行为作为直接判据。
- 匹配 Sandbox 账户与订阅。确认购买订阅和取消操作属于同一个测试账户，并核对产品标识、环境及订阅是否处于可测试状态。
- 从系统管理页取消。在设备的 Sandbox 订阅管理入口选择对应产品并取消；不要用应用内自定义按钮是否变灰来替代系统页验收。
- 检查结果并分流。配置式路径回看关联、资格和系统流程；实时路径同时比对请求日志、响应内容、超时及回退配置。若应用构建或签名本身失败，再独立检查 macOS/Xcode 工具链。
这套顺序也能回答“实时 API 没有响应时显示什么”：先看 App Store Connect 是否为该订阅配置了可展示消息；若没有，再查 API 默认消息。若两层都未设置或账户、订阅没有匹配，不能把默认存在某条自定义内容当作前提。
如果问题最后定位到缺少 macOS/Xcode 环境，构建和签名验收可以作为单独工作流处理；若阻塞点在资格、订阅标识或 API 响应，换构建机器并不能改变它们。你可以先查看 OSXPort 的远程 Mac 开发与验收指南，确认远程构建是否符合项目需求。相较于让 Windows/Linux 环境承担 macOS 专属构建、让性能不足的本地 Mac 持续跑 CI，或为偶发验收任务长期购置硬件，租赁 OSXPort 的远程 Mac 可为临时构建、签名和 Xcode 验收提供 macOS 环境；但它不能替代你所需的实体设备验证，也不应被当作修复 Sandbox 账号或 API 配置的方案。需要评估这条可选路径时，可查看 OSXPort 的远程 Mac 方案。