App Store 服务器 API 的新增功能

♪ ♪

Ian：大家好 我叫 Ian 是 App Store server 团队的 一名设计师 今天我将分享一些激动人心的关于 App 内购买项目服务器 API 的更新 包括新功能和重要更新 如果你不熟悉 我们提供两个主要的 API 帮助你充分利用在你的服务器上的 App 内购买项目 第一个是 App Store Server API 你可以从你的服务器上按需调用 App Store Server API 并返回你在 App 中进行的 App 内购买项目所需的所有数据 该 API 提供各种功能强大的端点 用于检索甚至修改 App 内购买项目数据

我们提供的另一个主要 API 是 App Store Server Notifications V2

通过 App Store Server Notifications V2 App Store 服务器会 主动向你的服务器 发送有关 App 中的 App 内购买项目的更新 这意味着你可以实时获取更新 而不需要轮询 App Store Server API

通知涵盖了全面的事件 包括订阅续订、到期、退款等等

这些事件让你能够跟踪 App 内购买项目的完整生命周期 以便更好地理解和响应用户行为

App Store Server API 和 App Store Server Notifications V2 具有许多出色的功能 它们都以熟悉的 JSON 格式提供交易数据 并且数据经过签名 所以你能相信这来自 Apple 你也可以同时使用这两个 API 来支持使用 StoreKit 2 或原始的 StoreKit API 的 App 我们根据你的反馈积极 支持这些 API 并提供新功能

今天我很高兴宣布 App Store Server API 和 App Store Server Notifications V2 的 最新专题更新

我们有许多新功能 在今天的讲座上 时间有限 我只能介绍其中一部分 请查阅我们的开发者文档 了解所有这些 新功能的详细信息 现在让我们深入了解这些出色的 App Store 服务器更新 我将分三部分介绍今天的更新内容 首先 我将详细介绍一些新功能 这让在服务器上处理交易更为简便 接下来 我将介绍改进的 App Store 服务器通知 帮助你可靠地确定用户订阅的状态 最后 我将提供有关迁移到 我们旧 API 的重要更新 让我们从交易开始 交易是 App 内购买项目的 核心数据对象 它们代表 设备上的 App 内购买项目 包含了有关该购买项目的重要信息 如产品标识符、类型、 购买日期等

App Store 服务器通过 一个使用 JWS 签名的 JSON 对象表示交易 这是一种安全的标准化的格式 你将在 App Store Server API 和 App Store Server Notifications V2 中看到

检索这些已签名交易的主要方式是 使用 App Store Server API 的 获取交易历史端点

该端点返回 给定用户在你的 App 中进行的 所有交易历史记录 因此你可以使用它来及时了解用户 从过去到现在的所有购买情况 但是 有时你的服务器 已经知道某个交易的存在 例如由于你的 App 向服务器发出的调用 在服务器端 你可能希望进一步验证该交易 并确保你拥有 最新的相关信息

以前 该用例需要调用 获取交易历史 并从响应中筛选出 匹配的交易 一旦找到 你可以使用 响应中的数据 刷新交易的记录

这个过程可能感觉很繁琐 特别是如果用户的交易历史 跨越多个页面 需要多次调用端点 而且若你在找已完成的可消耗交易 这种方法也不起作用 因为它们不会出现在 获取交易历史的响应中 因此 该用例需要一个 更具体的解决方案

这是今天我们引入 一个新的端点的原因所在 这样可以直接解决这个用例的问题 通过新的 Get Transaction Info 端点 你可以请求 单个购买的已签名交易信息 你只需要提供一个 transactionId

所有 transactionId 都被支持 无论产品类型或交易 在用户设备上的完成状态如何 没错 你甚至可以从该端点 获取已完成的可消耗项目

我们来快速查看新端点的工作方式 你向 App Store 服务器 新端点发送一个 GET 请求 包含 transactionId 作为路径参数

你将收到一个包含 signedTransactionInfo 字符串的响应

通过解码 signedTransactionInfo 你可以查看你在请求中提供的 交易 ID 的交易信息

就是这样 新的 Get Transaction Info 端点 非常简单 并且在处理服务器交易时更为灵活 我相信你会发现 它在各种使用情况中都非常有用 现在我们将灵活性主题进一步扩展

你可能熟悉 App Store Server API 的这些热门端点

每个端点都需要 一个 originalTransactionId 作为路径参数 这个 ID 用于告诉服务器 你正在为哪个用户请求或发送数据

但是 你可能并不是总有一个 originalTransactionId 如果你只有一个 transactionId 该怎么办？ 你可以将其发送到新的 Get Transaction Info 端点 以检索 originalTransactionId 但是为什么调用一个端点 只是为了调用另一个端点呢? 从今天开始 你可以使用任何 transactionId 调用这些端点

只需像以前一样 在请求的路径提供 ID 我们希望这种更大的灵活性将使调用 App Store Server API 的 这些核心端点比以往更加容易 如果你已经使用 originalTransactionIds 调用这些端点 不用担心 它们仍然可以正常工作 现在让我们转到即将推出的 App Store Server Notifications 的更新内容 如果你的 App 提供 自动续订订阅 这对你来说跟踪这些订阅的状态 以及它们随时间变化的情况很重要 在这里 你可以看到 订阅的五种可能状态 使用 App Store Server Notifications V2 你将及时收到 导致状态更改的事件的通知 因此你可以及时启用和禁用内容 还能保持用户体验的流畅性

让我们看看通知如何 提供有关订阅状态的信息 许多通知事件通过其类型 和子类型 直接指示订阅的状态 例如 具有 INITIAL_BUY 子类型的 SUBSCRIBED 通知

该通知表示用户 对你的产品进行了新的订阅 因此你知道 订阅的状态为激活

还有一个更简单的例子 通知类型为 EXPIRED

这明确指示 相关订阅的状态 现在为已过期

但对于某些通知 订阅状态 可能不太明确 以 REFUND 通知为例 当为你的 App 内购买项目 授予退款时 此类型通知就会发送 通过查看这个通知的 signedTransactionInfo 我们可以了解 退款是针对哪个购买项目

在这种情况下 我们可以看到退款 是针对一个自动续订订阅的 因此我们希望更新 我们对订阅状态的记录

这可能会误以为订阅状态 现在是被撤销 但事实并非一定如此 如果存在具有相同 originalTransactionId 的 近期的订阅续订购买 订阅的状态仍然可能为有效 如果是这种情况 你不应禁用 对订阅内容的访问

在这种情况下 订阅的状态非常不明确 仅凭通知中的数据 是不足以进行更新的 这并不是我们想要的结果 当你收到有关订阅的 App Store 服务器通知 我们希望 它能清楚地指示订阅的最新状态 以便你可以 在服务器上及时更新这些重要信息

因此 今天我们 引入了一个新的状态字段 将其包含在 App Store Server Notifications V2 的数据对象中 这个字段是一个简单的整数 代表我之前详细介绍的 订阅的五个核心状态之一

每个发送的自动续订订阅通知 都将包含这个新字段 现在 你可以在不必调用 App Store Server API 的 Get All Subscription Statuses 端点的情况下 获取订阅的状态 让我们看看这个新字段 如何改善我此前描述的情况 现在当你收到一个针对订阅的 REFUND 通知时 你可以简单地 检查状态字段 以了解订阅的状态

在此情况下 状态字段的值为 1 因此你知道相关订阅是有效的

新的状态字段使得 App Store Server Notifications 比以往更加有用 这非常有用 以至于你会想要 确保不错过任何一个通知 但如果你的服务器遇到故障 App Store 服务器可能 无法连接你的服务器发送通知

这就是为什么我们提供了 App Store Server API 的 Get Notification History 端点

该端点允许你请求过去六个月内由 App Store 服务器为你的 App 生成版本 2 通知

这样 当你的服务器遇到已知故障 你可以在故障期间调用该端点 并获取你的服务器错过的任何通知

然而 对于某些使用案例 这个过程可能不太高效 有时即便没有发生故障 你的服务器也可能会错过通知 例如临时的网络问题造成的情况 在这种情况下 你未必有明确的时间段查询该端点 只能筛选已经基本接收的通知页面 为了解决这种用例 我们正在 Get Notification History 中 引入一个新的请求字段 名为 “onlyFailures”

这个可选字段 将限制返回的通知仅为那些 未能到达你的服务器的通知 响应甚至将会包含当前 正在重试过程中的通知

现在 你能快速地将其 从故障和偶发的网络问题中复原 因为你只需要 解析尚未接收到的通知即可 我们来看看这个新字段的工作方式 你向 Get Notification History 端点发送一个请求 并在请求体中包含新的字段 onlyFailures

这是响应结果

notificationHistory 数组中的每个条目都表示一个通知 由于你在请求中包含了新的 onlyFailures 字段 因此在此列出的 每个通知都未能到达你的服务器 让我们缩放查看一个单独通知条目

在这里 我们有 signedPayload 我们可以解码此字符串 以查看通知的内容 就像它最初发送到你的服务器一样

通过查看此通知的 sendAttempts 数组 我们现在可以看到 每个发送尝试的结果 这个数组最多可以包含六个条目 其中一个是初始的发送尝试 最多可以有五次重试

在这里我们只看到两个条目 而且都失败了 所以这个通知仍然在重试过程中 如果后续的重试成功了 这个通知就不会再出现在 包含 onlyFailures 字段的后续请求中 这样就是新的 onlyFailures 字段的工作原理 我想你会发现它让 Get Notification History 变得更加有用

最后要讲的是将 App 从旧版 API 迁移到新版的重要信息 如果你的 App 已经提供 App 内购买项目功能一段时间 那么你可能熟悉 verifyReceipt API

在 2021 年 我们发布了 App Store Server API 作为从 App Store Server 获取 App 内购买项目数据的新方式 我们来比较一下这两个 API

使用 verifyReceipt 你可以验证和解码从运行原始版本 StoreKit 的客户端收到的收据 使用 App Store Server API 你可以使用这三个端点 获取与收据中相同以及更多的数据 App Store Server API 还提供了 各种其他端点 提供有用的数据和强大的功能 这些功能在其他地方找不到

来到我们的通知 API 我们仍然支持较旧的 App Store Server Notifications V1

但在 2021 年 我们推出了 App Store Server Notifications V2 现在我们来比较一下这些 API

App Store Server Notifications V1 和 V2 都提供 实时的 App 内购买项目事件 直接发送到你的服务器 但是 V2 通过使用类型和 子类型定义事件 从而提供了更高的清晰度 区别不仅仅在此 V2 还为其他事件提供通知 能够请求测试通知 访问通知历史记录 以及全新的状态字段 用于跟踪用户订阅的状态

通过采用 App Store Server API 和 App Store Server Notifications V2 你将解锁一系列新功能 安全高效地在你的服务器上 管理 App 内购买项目数据 这意味着你的客户将获得更舒适的 App 内购买项目体验 这就是为什么我们今天将宣布 停用 verifyReceipt 和 App Store Server Notifications V1 从今天开始 这些 API 将被视为已停用 不再接收功能更新

现在开始规划你的迁移 以享受更新 API 的所有优势

迁移只需要几个简单的步骤

要从 verifyReceipt 迁移到 App Store Server API 首先需要签署一个 JWT 来代表你的 App 这是一个简单的过程 在我们的文档中有详细说明 每当调用 App Store Server API 时 你将提供此 JWT 作为标头 以证明你拥有 所请求的 App 数据

接下来 你需要为每个用户保存一个 transactionId 在调用核心端点时 你将提供此 transactionId 作为路径参数 例如获取交易历史和 获取所有订阅状态 任何 transactionId 都可以使用 如果你维护了一个数据库 你很可能已经保存了一个数据库 如若不然 你可以从 每个用户的收据中提取一个

就是这样 然后 你就可以访问与以前从 verifyReceipt 中获取的相同 甚至更多的数据

从 App Store Server Notifications V1 迁移到 V2 更加简单 首先 准备好你的服务器 以解析新的 V2 格式 如果你已经在使用 App Store Server API 这一步应该很简单 因为 App Store Server Notifications V2 使用相同的 JWS 事务格式

一旦你的服务器准备就绪 请访问 App Store Connect 将你的首选项 从 V1 更改为 V2 通知 为了测试你是否迁移成功 你可以先在沙盒环境中 仅接受 V2 的通知

更换首选项后 App Store 服务器将会 以 V2 格式发送新的通知 如果你有任何 V1 版本的通知 处于重试过程中 最多在三天内你可能会 继续收到这些通知

对于迁移的更多帮助 我们提供了其他可用资源 App Store Server API 和 App Store Server Notifications V2 在沙盒环境中可用 所以将其发布到正式环境前 你可以使用沙盒环境进行测试

本周 我们还发布了 App Store Server 库 这是一个用于调用 App Store Server API 和解析 App Store Server Notifications V2 的 全新开源库 它可以帮助你轻松调用我们的端点、 验证你收到的签名数据 甚至从收据中提取 transactionId 使迁移更加容易

我希望你能观看 今年 WWDC 的专门讲座 主题是 “了解 App Store Server 库” 有关如何迁移的更多信息 请观看 WWDC22 讲座 主题是“探索 App 内购买项目 集成和迁移”

本次讲座的 App Store Server 更新内容就到此为止了 我希望你能充分利用我们今天介绍的 精彩好用的新功能 你也可以查阅我们的文档以了解 更多因时限尚未介绍的功能

每个功能现在都可以 在沙盒和生产环境中使用 所以你可以先在沙盒中进行测试 然后在准备好时 将其部署到你的生产服务器上

我们非常乐意听取你的意见 如果你对 App Store 服务器 有功能请求 请通过 Apple 的 反馈助理告诉我们 感谢参与 WWDC23！ ♪ ♪