了解 App Store Server Library

♪ ♪

Dave：大家好 我是 Dave Wendland 是 App Store Commerce 团队的技术推广工程师 我和我的同事 Alex 将探讨 全新的 App Store Server Library 及其一系列函数将如何 从为 App Store Server API 生成 JWT 到迁移离开 verifyReceipt 端点用于购买验证 让你的服务器能够利用各种功能 当我们回顾过去时 App Store 于 2008 年推出 当时的 App 仅可免费下载或收费下载 不久后 我们增加了 App 内购买项目 自那时以来 开发者社区的规模和复杂性 在全球范围内都得到了增长 App Store 继续为 开发者和用户推出更新 以支持充满活力的 全球移动 App 生态系统

2021 年 我们发布了 StoreKit 工具的下一个时代 包括经过改进的 StoreKit 框架 App Store Server API 以及 App Store Server Notifications V2 随着 2022 年 和今年 WWDC 2023 的更多更新 这些工具以签名的 JWS 格式 提供交易和状态信息 它们旨在为开发者提供客户端 和服务器端的强大信息 这一系列的 API 促进了 App Store Server Library 的诞生 我们很自豪地告诉大家 这个资源库提供了一套函数 使我们的开发者社区更容易采用 和集成当今和未来的最新 API 该资源库的 Beta 版支持四种语言： Swift、Java、Node 和 Python 你可以根据 自己的后端环境和专业知识 选择最合适的语言来使用 每种语言的 App Store Server Library 都可在 GitHub 上找到 我们期待你的反馈 和参与 我将资源库所提供的内容分解为 四个关键功能 首先 最强大的 功能是 App Store Server API 通过简化 JWT 的生成过程 你可以随意使用 App Store Server API 提供的数十个不同端点

其次 核心功能是 验证 JWS 已签名数据 以确保你的交易和服务器通知 由 Apple 生成并签名 接下来是提取收据交易工具 这个简单的工具 可以从 App 收据中提取交易标识符 这样做可以减少 你使用 verifyReceipt 端点的需求 并让你能够 迁移到 App Store Server API 进行购买验证和其他功能 这提供了支持你当前 和遗留 App 版本的清晰路径 最后 还有生成 订阅促销优惠签名的实用工具 这个工具可以使用 你的 App 内购买项目私钥 进行签名和生成优惠 如果你对订阅促销优惠不熟悉 可以在我们的讲座 “订阅优惠 最佳实践” 中进一步了解更多信息 现在让我们深入探讨 这些核心资源库函数中的三个功能： App Store Server API， 已签名数据验证 以及迁移到 App Store Server API 让我们从 App Store Server API 开始

该服务器 API 的基础是 Get Transaction History 端点 只需使用交易 ID 该 API 就能提供客户 完整的 App 内 购买项目交易历史记录 除了该端点外 它还具备更多功能 该 API 具有十几个端点 所有这些端点都需要 某种形式的身份验证 即 JSON Web Token 生成你的 JWT 是一个关键步骤 如果你对这个过程不熟悉 这就是资源库的用途所在 现在由 Alex 来演示如何设置资源库 以便与 App Store Server API 一起使用 Alex：大家好 我是 Alex Baker 一名 App Store 服务器工程师 我将演示如何开始 使用 App Store Server Library 以及如何调用 App Store Server API 这个演示将逐步介绍收集配置 App Store Server Library 所需的信息 并展示创建 API 客户端并调用 API 的示例 我现在开始在 App Store Connect 中获取必要的信息 这些信息将在使用资源库时 与 App Store Server API 一起使用 进入“用户和访问”模块……

然后进入“密钥”选项卡 再选择“App 内购买项目”选项

这里有一些有用的信息 首先是发行者 ID 接下来 我将生成一个新的私钥 给私钥命名 然后点击生成 生成密钥会提供两个信息： 密钥 ID 和下载私钥的选项 只能下载一次 切换到 Apple 公钥基础设施网站 看到左上角的 Apple Root Certificates 部分 下载根证书

这是一个使用 Gradle 编译系统的简单 Java 项目 首先 在项目中添加对 App Store Server Library 的依赖项

切换到 ExampleApp 类 在这里是之前获取的信息： 发行者 ID、密钥 ID 和私钥 此外 将 App 的 bundleId 存储起来

在此演示中 我使用沙盒环境 并存储适当的枚举值

使用这些信息 实例化 一个 AppStoreServerAPIClient 使用这个客户端 调用 TestNotification 端点 向你在 App Store Connect 中配置的 URL 发送一个类型为 TEST 的通知 最后 打印出 testNotificationToken 运行后 我们将看到 testNotificationToken 被打印出来 如预期所见 我们看到了该令牌

这演示了如何使用 App Store Server Library 以简化使用 App Store Server API 以及 App Store Connect 中的所需信息 现在由 Dave 继续介绍 Dave：谢谢 Alex 该演示真正说明了 这个资源库帮助你设置 并生成用于与 Server API 通信的 JWT 的速度之快 当你采用我们的 API 时 该资源库将对你的 实施时间表产生重要影响 虽然使用该资源库很有帮助也简单 但没有什么比安全地存储你的 App 内购买项目私钥更重要的了 如果你认为你的密钥可能已被泄露 你可以随时在 App Store Connect 中生成新的密钥 在你开始开发之际 我们建议从 沙盒和 TestFlight 交易开始 最后 请确保定期检查 已更新的 Apple 根证书颁发机构 现在我们来谈谈 为什么已签名数据验证 对于你的 App 内 购买项目业务来说是基础性的操作 首先 我们来谈谈 已签名数据包含的内容以及其重要性 StoreKit 签名数据意味着它是由 App Store 以 JSON Web Signature 格式生成和签名的 它包含了关于 App 购买、App 内购买项目 客户事件和客户订阅状态的数据 最常见的两种签名数据负载是 JWS Transaction 和 JWS Renewal Info 然后 appTransaction 包含了 关于最初购买的 App 版本 以及当前安装在设备上的版本的 详细信息 然后我们有 App Store Server Notifications V2 该通知本身是签名数据 并且还可能包含 JWS Transaction 和 JWS Renewal Info

作为提醒 只有在 iOS 15 及更高版本的 StoreKit 2 中 以及在 App Store Server API 和 App Store Server Notifications V2 中 你才会找到这些 JWS 已签名数据

建议你在以下 任何事件之后 验证 JWS 已签名数据： 当在设备上提供或解锁内容时 或者当你的服务器 收到已签名数据时 无论是来自你 自己的 App、另一个服务器 还是 App Store 服务器通知 最后 当你收到来自 App Store server API 的响应时 现在让我们来看看 Alex 演示如何验证 JWS 已签名数据 以及资源库是 如何为你处理这个问题的

Alex：在这一部分 我将展示如何验证来自 App Store 的已签名数据 我将描述你需要执行的验证过程 然后 我们将介绍 App Store Server Library 的 SignedDataVerifier 类 如何为你执行此过程 我想强调 当你对 RFC 和协议不熟悉时 使用类似 App Store Server Library 这样的工具是非常明智的 这是一些来自 App Store 的已签名数据 看起来这里有很多内容 颜色编码显示有三个部分 每个部分之间由句点分隔 并以 Base64 URL 编码形式呈现 第一个和最大的部分是标头 解码后 标头是一个由 JWS 规范定义的 JSON 结构 在这种情况下 我们的标头只有两个字段： 首先是算法 始终为 ES256 然后是一个名为 x5c 的字段 这是一个证书数组 用于计算 签署 JWS 的预期公钥 让我们回顾一下证书链构建过程 数组中的第一个证书是叶证书 该证书的公钥签署了 JWS 为了验证该证书来自于 Apple 构建一条信任链 追溯到已知的受信任来源 在这种情况下 即 Apple 根证书颁发机构 数组中的下一个证书是 是 Apple Worldwide Developer Relations 中间证书颁发机构 将其视为更专门针对 开发者的 Apple 根证书颁发机构的版本 证书链的最后一个证书 是 Apple 根证书颁发机构 这样我们就知道 该链是由哪个 Apple 机构发起的 提醒一下 验证 证书与之前获取的根证书 完全匹配非常重要 这些根证书是从 Apple 的 公钥基础设施网站上获取的 第一步是验证 每个证书是否由证书链中的 前一个证书签名 然后执行额外的 验证步骤 l例如确保每个证书具有 有效日期、正确的格式等 接下来 验证这些证书 是否来自 Apple 并且它们的目的是 用于签署 App Store 数据 而不是与其他无关的用例相符合 这些无关用例不适合 用于签署 App Store 数据 对于验证叶证书 通过检查 Mac App Store Receipt Signing 的 对象标识符 (OID) 来确认其目的 对于中间证书 检查 Apple Worldwide Developer Relations 的 中间授权 OID 最后 正如之前所述 确保根证书颁发机构 是你存储的 Apple 根证书 颁发机构之一 现在让我们实际解码 一个叶证书并观察 如何检查这些值

这是由 OpenSSL x509 命令生成的 证书的 X509v3 扩展部分

在底部是 上一张幻灯片中所列的 OID 表示证书的目的 是 App Store 收据签名 然而 还有一些其他需要检查的重要字段

在这里 我们可以 看到授权信息访问部分 该部分提供有关发行者的信息 以及检查证书 是否被吊销的重要信息 在进行验证过程之前 使用在线证书状态协议 (OCSP) 检查证书是否被吊销 关于如何执行此操作的过程 和加密过程在 RFC 6960 中有定义

在验证证书链之后 请检查 JWS 是由叶证书的公钥签名 取出之前的叶证书 提取叶证书的公钥 将密钥和原始 JWS 传递给 JWS 签名验证函数 验证函数检查数据是由 公钥签名 并解码有效负载 到这里该过程几乎要完成了 但还有一个额外的验证步骤 这是一个解码的 App Store Server TEST Notification 之前的步骤 验证了数据来自 App Store 然而 还要检查通知是针对 你的正确 App 和环境

通过检查 appAppleId 和 bundleId 确认通知 是针对你的正确 App 检查环境是否与预期环境匹配

与验证过程中的其他步骤一样 App Store Server Library 在执行验证时也会进行这些检查

这就完成了来自 App Store 的 已签名数据验证过程 接下来 我将扩展之前的项目 使用包含在 App Store Server Library 中的 SignedDataVerifier 类来验证签名数据 SignedDataVerifier 类 执行之前介绍的验证步骤

在这个演示中 我将收到我之前请求的测试通知 然后验证和解码签名的通知 在请求测试通知 和服务器 接收到通知之间有一小段延迟 因此添加五秒的延迟 接下来 使用之前 获取到的 TestNotificationToken 调用 GetTestNotificationStatus 端点 最后 打印通知的 前几个字符以确认成功 GetTestNotificationStatus 端点返回发送尝试的结果 以及通知的有效负载 我们应该看到有效负载的开头部分

正如预期的那样 我看到了通知的前几个字符 接下来 创建一个已签名数据验证器 这需要三个信息 首先是 Apple 根证书颁发机构的列表

我之前下载的证书 现在在资源文件夹中 将根证书导入到一个集合中 由于我正在使用沙盒环境 所以不需要 App 的 Apple ID 在沙盒里可以传递 null 代替 Apple ID 最后 确定是否执行吊销检查 由于通知刚刚被接收到 因此 onlineChecks 应设置为 true 对于几个月或几年前接收的通知 onlineChecks 应为 false 因为证书可能已过期 将这些字段传入 新的 SignedDataVerifier 然后 将之前收到的通知传入 并打印结果 然后运行程序

完成后 程序将显示 已验证和解码的通知 由于这是一个 测试通知 它的类型将为 TEST 并且在 有效负载中会有 App 的标识符 以及一些其他字段

正如预期的那样 我看到了 一个类型为 TEST 的已解码通知

我们在之前的演示中扩展了内容 以演示 SignedDataVerifier 对象 现在由 Dave 来回顾一些最佳实践 Dave：哇 这真实地展示了 验证已签名数据所需的所有步骤 以及资源库 如何为你处理这种复杂性 因此一定要使用 SignedDataVerifier 进行服务器端验证 重要提醒：在验证数据时 你仍然需要确认 App 和产品标识符 以确保为正确的 App 或服务 授予或撤销购买 最后 由于证书可能过期或被吊销 不要在客户端 或服务器端硬编码 任何证书 并始终验证其是否有效 我们将介绍另一个 App Store 服务器工具 用于帮助 将你的服务器端 App 收据验证 从 verifyReceipt 端点 迁移到 App Store Server API App Store Server Library 提供了一个工具 专门用于此迁移 并确保没有 App 被遗漏 考虑迁移到 App Store Server API 有很多理由在你的 规划中优先考虑这项工作 该 API 支持购买验证 并提供其他端点 用于客户支持、安抚 以及测试 App Store Server Notifications V2 随着我们不断更新和发布新属性 这些属性 仅与 JWS 签名数据一起发布 且 StoreKit 2 App Store Server API 以及 App Store Server Notifications V2 均支持该签名数据 另一个好处是 你需要记录的数据仅仅是 一个原始交易 ID 或交易 ID 无需在你的帐户系统中 保存 Base64 编码的收据 鉴于我们对 最新 API 的持续投资 我们已宣布 verifyReceipt 端点现已弃用 如欲进一步了解 请观看讲座 “App Store Server APIs 的最新内容” 来了解详细的更新和指导 现在由 Alex 分享 App Store Server Library 如何帮助你进行迁移 Alex？ Alex：谢谢 Dave 现在让我们来 看一下 App 收据的流程图 虽然 StoreKit 2 和 App Store Server API 是非常棒的工具 在你的服务器上支持使用较旧设备 或最近未更新的用户非常重要 对于这些用户 只能提供 App 收据作为验证信息 我将展示先前如何支持这些设备 以及在 verifyReceipt 弃用之后 如何继续支持这些客户端

首先 设备将收据发送到你的服务器 在旧的模式中 你的服务器将此收据传递给 verifyReceipt 然后接收解码后的收据

响应中包含一个 originalTransactionId 将其传递给 App Store 服务器的 Get Transaction History 端点 在 App Store Server API 中使用 App Store 服务器 返回已签名的交易 你可以用它们来为客户提供服务 现在由于 verifyReceipt 已被弃用 让我们替换这个部分 在 App Store Server Library 的 收据工具中 直接从收据中提取交易 ID 然后将该交易 ID 传递给 App Store Server API 消除了进行两次往返的需要 之后 将端点返回的修订版存储起来 这样就无需 每次重新解析整个历史记录

由于从 App 收据中提取的值 可能是原始交易 ID 也可能不是 我们很高兴地宣布 我们的许多端点 包括 Get Transaction History 端点 现支持任何交易 ID 作为参数 而不仅仅是原始交易 ID 现在我将演示如何使用 App Store Server Library 提取交易 ID 并将其用于调用 Get Transaction History 端点 以获取相应的交易历史记录 在这里 我将获取一份 App 收据 提取其中的交易 ID 然后使用该 ID 调用 Get Transaction History 端点 首先 App 收据 你可以从设备或 App Store Server Notification V1 中获取 App 收据 我在这里已经有一个了 接下来 创建 receiptUtility 类的实例 为了提取交易 ID 需要调用从 App 收据中 提取交易 ID 的方法 并非所有的收据都会有交易 ID 有可能用户没有任何购买记录 因此 添加一个空值检查

为了更深入地解决这个问题 想象一下我们想要获取关于 该用户最近的可消耗产品的信息 并排除被撤销的消耗产品 创建一个 TransactionHistoryRequest 对象 指定只想要消耗品类型的产品 以排除被撤销的交易 并要求以降序返回数据

我们需要两个 辅助对象、一个响应变量 和一个交易列表 使用 do while 循环遍历 来自交易历史端点的响应 如果这不是第一个请求 从前一个响应中 获取修订令牌以继续分页浏览数据 然后 从 App 收据中的 交易 ID、请求对象 和修订令牌 调用 getTransactionHistory 端点 最后 将响应中的 所有交易添加到交易列表中 重复此过程 直到响应中的 HasMore 字段为 false 打印出交易列表以查看结果

这里我看到了 从 API 返回的交易列表 可以使用之前 演示中的 SignedDataVerifier 进行解码

感谢你参加我们的最后一次演示 本次讲座演示了如何使用 App 收据和 App Store Server API 请 Dave 来带我们总结 Dave：对于新的 App Store Server library 我感到十分兴奋 我认为这些功能能够 帮你更轻松地采用我们的 API 并过渡到 App Store Server API 这是 App Store Server API 在 Github 上的 Java 代码存储库的截屏 在此页面上 你可以找到我们的文档链接、 提交拉取请求 并找到如何使用资源库的示例 很快你就可以下载 App Store Server Library Beta 版了 并开始规划采用 App Store Server API 我们期待你的反馈和功能请求 请通过反馈助理 和 Github 与我们联系 谢谢你 ♪ ♪