探索适用于 App 内购买项目的 App Store Server API

大家好 欢迎观看“探索适用于 App 内购买 项目的 App Store Server API” 我叫 Alex 是 App Store 服务器团队的工程师 我叫 Ian 也是 App Store 服务器团队的工程师 在本讲座中 我们将介绍 App Store 上 适用于 App 内购买项目的 服务器 API 我将带大家了解服务器 API 的 一些用例 展示如何只使用设备端代码 实现更多可能 在我讲的部分 我将详细介绍 App Store 服务器 API 即将推出的新功能 无论你是已经拥有服务器 还是刚刚入门 都有值得你期待的功能 要介绍的内容很多 让我们开始吧 作为 App 开发者 你可能熟悉 App Store Connect 你可以用它来配置 App 的设置和产品 你可能也熟悉 StoreKit 你用它在 App 中添加 App 内购买功能 这两项都是必备技术 但你还可以利用 第三项技术 将 App 内购买 提升到新的水平 这种技术就是 App Store 服务器

App Store 服务器 包括三个重要部分 首先是 App Store 服务器 API App Store 服务器 API 可让你 从你的服务器向 App Store 服务器发出请求 可让你查询有关交易的信息 还可让你提交与这些交易相关的信息 例如延长订阅的续订日期

利用 App Store 服务器 API 中的四个端点 你可以获取有关交易的信息 例如获取顾客的交易历史记录 另外五个端点 与退款和顾客满意度有关 例如 你可以发送消费信息 以参与退款决策过程 最后三个端点 用于 App Store 服务器通知 你可以通过这些端点 触发测试通知并查看通知历史记录

总之 App Store 服务器 API 的 这 12 个端点 取代并超越了 2023 年废弃的 Verify Receipt 端点功能 现在 我已经介绍了 可用于调用 App Store 的端点 App Store 服务器通知 允许 App Store 调用你的服务器 App Store 服务器通知 允许 App Store 主动将交易更新通知你的服务器

App Store 可以在 订阅生命周期内将 升级或续订等事件通知你的服务器 通知还包括退款生命周期 例如在发生退款时通知你

接下来介绍 App Store Server Library App Store Server Library 是 使用 App Store 服务器 API 和 App Store 服务器通知的基础 App Store Server Library 旨在简化 你与 App Store 服务器的整合

它为 App Store 服务器 API 提供一个客户端 让你比以往任何时候 都更容易开始使用这些端点

它内置签名数据验证功能 让你可以验证和解码来自设备、 App Store 服务器 API 或 App Store 服务器通知的数据 这个资源库还允许从弃用的收据中 提取交易信息 作为过渡路径来告别弃用的 Verify Receipt 端点 和 Original StoreKit 客户端框架

此外 它还提供了一种创建 促销优惠签名的简单方法

去年 我们很高兴发布了 生产就绪版本 1.0 共有四种语言版本 分别是 Java、Python、Node.js 和 Swift App Store Server Library 现在是通过这些语言 使用 App Store 服务器 API 的推荐方式 开始使用时 你可以通过每种语言的 相应软件包管理器下载这个资源库

这个资源库的另一大特点是 它是开源的 我们鼓励你提交 反馈和开放拉取请求 欢迎访问 GitHub 了解入门信息 并考虑加入不断壮大的开发者社区 成为社区的一员 为这个资源库做出贡献

有关 App Store Server Library 的使用和设置的更多信息 请观看我们的 WWDC23 讲座 “了解 App Store Server Library” 现在我已经介绍了 App Store 服务器的基础知识 接下来我将介绍今天讲座的 三个核心主题 每个主题我都会分享一些最佳实践 然后 Ian 将分享新功能 首先我将介绍购买生命周期 Ian 将分享 App Store 服务器通知 的新功能 接下来 我将讨论内容交付 以及如何从服务器角度 处理这一工作流程 然后 Ian 将分享这个领域的 一些增强功能 最后 我将分享订阅和 优惠领域的新发展 Ian 将介绍这些交易 可用的新字段 让我们从购买生命周期开始

App 内购买类型多种多样 这里简要介绍一下 非消耗型项目是只需购买一次 即可终身使用的产品 消耗型项目 顾名思义 就是可以用完的产品 顾客可根据需要重新购买 例如 一包 100 颗的宝石 就是消耗型项目 这些宝石可以用来购买游戏中的物品

非续期订阅与消耗型项目类似 用户可以在期限结束后重新购买 自动续期订阅是标准订阅 可按计划续订 在续订或流失的情况下 也可以重新购买 这就是 App 内购买 类型的简要介绍 现在为了进一步了解购买生命周期 我将以消耗型项目购买为例进行讲解 顾客在 App 中购买消耗型项目时 工作流程开始

顾客的设备会收到一项已签名的交易 然后你的 App 可以 将这个交易发送到你的服务器 以验证交易并分发内容 此外 App Store 服务器会向你的 服务器发送带有 相同签名交易的 ONE_TIME_CHARGE 通知 通常情况下 这一购买流程的生命周期到此结束 顾客准备购买另一个消耗型项目 但是如果顾客要求退款会怎样呢

这时 App Store 服务器 可能会向你的服务器 发送 CONSUMPTION_REQUEST 通知 要求你提供有关顾客 对产品使用情况的信息 你可以通过调用 Send Consumption Information 端点 来提供这一信息 你提交的信息 将用于 Apple 的退款决策过程

一旦 Apple 批准或拒绝退款 你将收到 REFUND 或 REFUND_DECLINED 通知 用于将结果告知你的服务器

这个工作流程的后半部分乍看起来 可能有点令人生畏 但 App Store Server Library 可以提供帮助 下面是使用 App Store Server Library 实现消费请求 工作流程的一种方法 我在本例中使用的是 Java 但这个资源库也适用于 Node、Python 和 Swift on Server

首先我创建了 SignedDataVerifier 和 AppStoreServerAPIClient 为简洁起见 我在这里省略了参数 接下来 假设我最近收到了一个通知 并在 signedNotification 变量中 以字符串的形式 存储了已签名的有效负载 与任何通知一样 我会使用 SignedDataVerifier 对有效负载进行验证和解码 并将解码后的对象存储到通知变量中

现在 在这种情况下 我会检查 NotificationType 是否等于 CONSUMPTION_REQUEST 如果等于 我就继续 执行这个类型的相应逻辑

我从通知的数据对象中 获取 signedTransactionInfo 并将它存储在字符串中 然后 我使用 SignedDataVerifier 提取并验证已签名的交易 并将 transactionId 保存 在一个变量中 接着 我将构建 consumptionRequest 对象 然后发送到端点 如何为这个对象确定合适的值 将因情况而异 具体取决于你的服务器实现 和手头的交易

我这里有几个示例值 表示向顾客提供的示例内容 以及在 Apple 平台上 消费的内容

构建 consumptionRequest 对象后 我就使用前面 创建的 apiClient 来调用 Send Consumption Information 端点 我传入 transactionId 和 consumptionRequest 如果没有抛出异常 就说明数据已成功提交 这就是使用 App Store Server Library 处理消费请求工作流程的方法 现在 Ian 你有关于这个领域 新功能的最新信息吗 当然 我们有一些很棒的新功能 可以改善对购买和退款的处理 首先是一次性收费通知 Alex 在他的消耗型项目 工作流程示例中介绍过这种通知 这种全新的通知类型 适用于一次性购买 App 内产品 现在 当有人在你的 App 中购买 消耗型项目、 非消耗型项目或非续期订阅时 你的服务器就会收到通知

这种通知是对现有通知类型的补充 即补充我们为新购买和续订 自动续期订阅发送的通知 通过侦听这些类型和一次性收费 你的服务器将随时了解顾客 在你的 App 中进行的 每一次购买

这一新通知今天在沙盒中推出 可供你开始进行测试

并将于今年晚些时候投入生产

这里是一个解码 ONE_TIME_CHARGE 通知的示例 通知类型是 ONE_TIME_CHARGE

解码后的交易信息 包含 App 内购买的 所有相关数据

在这个示例中 顾客购买了 一包 100 颗宝石的消耗型项目 如果你在购买时 提供了 appAccountToken 你可以在这里找到这个项目 你可以使用这个值了解 是你服务器上的 哪个顾客账户购买的 这样 你只需使用 通知中提供的数据 即可立即解锁这次购买的内容 现在 你无需调用 App Store 服务器 API 或等待设备端的调用 购买生命周期的一个重要部分是退款 正如 Alex 提到的 目前 有人请求对 App 内购买的 消耗型项目进行退款时 就会发送 CONSUMPTION_REQUEST 通知 正如 Alex 指出的 你可以通过调用 Send Consumption Information 端点进行响应 但如果你在 App 中提供 自动续期订阅 又会怎样呢 我们希望你能更多地 参与退款决策过程 因此现在我们也会为自动续期订阅 提交的退款请求 发送 CONSUMPTION_REQUEST 通知

此外 所有 CONSUMPTION_REQUEST 通知中 现在都包含一个名为 ConsumptionRequestReason 的新字段 这个字段表示顾客要求对 App 内购买项目进行退款的原因

这是为自动续期订阅发送 CONSUMPTION_REQUEST 通知的示例

新字段 consumptionRequestReason 指明了顾客要求退款的原因 在本例中 顾客不小心进行了购买

我们还更新了响应 CONSUMPTION_REQUEST 通知的 流程 当你调用 Send Consumption Information 时 你需要提供有关购买者 对产品使用情况的上下文信息 但如果你愿意 我们希望你在 决策过程中扮演更积极的角色 因此 你现在可以在调用 Send Consumption Information 时 提交一个表明是同意还是 拒绝退款的偏好值

你可使用 CONSUMPTION_REQUEST 通知中 新的 consumptionRequestReason 字段来指示这个偏好值 你的偏好值 和提交的任何其他消费数据 都将在最终决策过程中加以考虑 现在 在 Alex 代码的基础上 我将向大家展示如何通过 App Store Server Library 使用这些新功能 用于解码通知和获取交易信息的 代码保持不变 但现在通知数据包含 新的 ConsumptionRequestReason

如果你想表达自己对于接受 还是拒绝退款的偏好 可以根据自己的逻辑来确定这个偏好 作为示例 我在这里提供了一个针对 名为 determineRefundPreference 的自定方法的调用 在这种方法中 你可能需要考虑 消费请求原因 和交易以及其他数据

最后 在 ConsumptionRequest 对象上设置 refundPreference 然后像以前一样将它 发送到 App Store 服务器 就大功告成了 使用 App Store Server Library 时 整合新功能 只需几行代码

发送消费信息是你在退款过程中 发挥更大作用的一种方式 但你最重要的职责是 提供无缝的购买体验 把不会产生退款请求放在第一位 因此 要采用的方法之一就是确保 使用你 App 的用户能立即访问 他们购买的内容 Alex 在这方面你有什么建议吗 问得好 Ian 让我来分享一些内容交付方面的 最佳做法 首先 让我们了解一下使用 服务器进行内容交付的 工作流程 首先顾客购买 App 内产品 随后 你的 App 将签名的交易信息发送到你的服务器 这时 你将授予用户 访问产品的权限 例如 对于消耗型项目 你可能 在你的服务器上更新用户的 游戏币余额 你向设备上的 App 发出信号 表明交易内容已被授予 然后 你的 App 会 将交易标记为已完成 将交易标记为已完成 可向 App Store 表明 内容已被授予 顾客已准备好进行 另一项购买

让我们把重点放在内容授予步骤上 这里是一些通过服务器 授予内容的最佳实践 由于你可以全权控制你的服务器 因此你的服务器应该是顾客 所访问内容的唯一真实来源 请勿依赖设备作为你系统中 顾客所拥有内容的真实来源 因为设备上或设备与你服务器之间 未签名的数据可能会被修改 此外由于你的服务器只负责授予内容 因此你的服务器也应该是 已授予内容的真实来源 你的服务器为设备端交易授予内容后 你的 App 就应将交易标记为 已完成以作为向 App Store 服务器发出的信号 但是你不应将交易的完成状态 作为内容交付的指标 否则可能导致你多次授予 内容或完全未授予内容

无论你的服务器从哪里获得 已签名的交易 都要在授予内容之前验证签名 我们之前看到 使用 App Store Server Library 可以轻松做到这一点 你的服务器负责授予所有内容 因此服务器必须快速发现新交易 和更新的交易 以提供最佳的顾客体验 为确保你的服务器不会错过交易 有很多种方法 例如 将所有新交易和更新的交易 从设备发送到服务器 为你的 App 启用 App Store Server Notifications V2 所有购买都会生成通知 包括续订等 续订在顾客不使用 App 时 也可能发生 这样 你就可以发现 顾客的购买行为 而无需依赖设备 使用 StoreKit 设置 你的服务器在顾客购买时 生成的 appAccountToken 当你收到有关购买的 App Store 服务器通知时 你可以使用这个值 将包含的交易数据 通过链接发送给顾客 而无需使用设备 或者 如果你有理由 相信你错过了一次购买 你可以使用 App Store 服务器 API 的 Get Transaction History 端点 来获取顾客的历史记录 并检查是否有任何错过的交易更新

这里是一个有关如何使用 App Store Server Library 调用 getTransactionHistory 端点的示例 在这里 我的 apiClient 和刚才一样 并假设顾客有一个 transactionId 我可以使用顾客的 任何一个 transactionId 来获取他们的完整交易历史记录

接下来 我将构建请求 这个端点支持各种筛选和排序选项 在这里 我只需指定我想要 交易按最后修改日期 升序排列 我创建了一个 HistoryResponse 变量来保存来自端点的响应 一个 List 用于存储已签名的交易 一个 String 用于保存修订 由于这是我第一次 调用这个用户的端点 修订应该为空 如果我以前获取过 这个用户的交易历史记录 我可以提供最新 HistoryResponse 中的修订 以便只获取新更新的交易

为发出请求 我会传入 transactionId 上一个请求返回的 修订 (如果存在的话) 以及请求对象 我将响应中所有已签名的交易 添加到输出列表中 然后更新修订变量 以便随时获取下一组交易

这个端点是分页的 因此 我会循环遍历 调用端点的代码 直到响应中的 HasMore 字段为 false 表明没有更多的交易

循环结束后 我就会得到 这个顾客所有交易的列表 然后就可以使用 SignedDataVerifier 进行解码 就像我们刚才看到的那样 然后 我就可以检查这个列表 查看是否有新交易和更新的交易 并采取适当的行动 例如交付内容 这就是如何通过 App Store Server Library 使用 Get Transaction History 看起来不错 Alex 你真的可以用这个端点 获取每笔交易吗 不完全是 这个端点只会返回设备端已退款、 已撤销或未完成的消耗型项目交易 但自从这个端点首次推出以来 一直都是这样 听起来是该更新了 今天 我们发布了 新版本的 Get Transaction History 这个端点的版本 2 会返回给定顾客的所有交易 无论产品类型、 退款状态或完成状态如何 这是顾客真正完整的交易历史记录 开辟了全新的使用案例 例如 你可用这个记录向 顾客展示他们完整的购买历史 或者刷新某位顾客的 服务器端购买条目 甚至可以在你的服务器上审核用户的 消耗型项目余额 以确保所有支出都处于最新状态

新版 Get Transaction History 会返回与原始版本 相同的所有数据 甚至更多 因此 原始版本现已弃用

迁移非常简单 因为 新端点与原始版本 非常相似 只需将 URL 路径中的版本 更新为 V2 让你的服务器准备好处理 已完成的消耗型项目交易 就可以开始使用了 通过 App Store Server Library 使用新版本的 Get Transaction History 非常简单

如果我们重温一下 Alex 的代码 唯一的变化在于对端点的调用

新版本参数让你可以选择 要调用的端点版本

你可以像以前一样 根据响应来填充交易列表 但要记住 已签名的交易列表 现在包括所有消耗型项目

这就是交易历史记录的最新内容 但如果完整的交易历史记录 完全是空的 那又有什么用呢 产生大量交易 的方法之一是在 App 中 提供自动续期订阅 吸引新订阅者和留住现有订阅者 需要持续努力 但这是非常值得的 Alex 能不能向我们介绍 一些有助于实现这一目标的方案呢 求之不得 接下来 我将讨论订阅和优惠 包括如何使用优惠来吸引和留住 订阅产品的顾客 首先 我将介绍 自动续期订阅产品的 三种付款模式

在创建优惠时 可以配置几种不同的付款模式 其中一个方案是为顾客提供免费试用 免费试用是 鼓励顾客在付费前试用服务的 好方法 另外 你还可以向顾客提供 随用随付模式的优惠价格 如两个月半价

最后 你可以向顾客提供预付优惠 让顾客以优惠价格 预付一段时间的费用 现在我们介绍了各种付款模式 下面我将介绍各种优惠类型 首先是推介促销优惠 推介促销优惠适用于 订阅群组的新订阅者 这些优惠的资格和分发 由 Apple 负责 从而确保顾客之前 没有兑换过特定优惠 接下来是优惠代码 这些代码可以分发给你的顾客 并在你的 App 中兑换以获得优惠 Apple 会确保代码只能兑换 你指定的次数 而你可以决定向哪些顾客分发代码

接下来是促销优惠 这些优惠可用于留住现有顾客 或鼓励流失订阅者回归 这些优惠在设备端提供 资格的判定完全由你控制

最后是新的赢回优惠类型 可以向流失的顾客 显示赢回优惠 以赢得他们的回归

有关这种新优惠类型的更多信息 请观看 WWDC24 讲座 “实现 App Store Offers”

在所有优惠类型中 促销优惠 最依赖服务器逻辑 因为这种优惠需要签名才能分发 而资格逻辑则取决于你 接下来 我将详细介绍工作原理

下面是促销优惠工作流程的 一个示例 假设我们有一位老顾客 停用了订阅的自动续期功能 这意味着这位顾客的订阅 很快就会流失

App Store 服务器会通过 类型为 DID_CHANGE_RENEWAL_STATUS 以及子类型为 AUTO_RENEW_DISABLED 的通知 来告知你这一情况 现在你可以选择 向顾客发送促销信息 鼓励对方继续订阅

如果你决定顾客应该收到特定优惠 你的服务器就需要创建 一个促销优惠签名 发送到顾客的设备上 你的 App 向 StoreKit 提供签名 以便向顾客提供以 促销价格购买产品的选项

你将通过 SUBSCRIBED 或 OFFER_REDEEMED 通知 来了解兑换情况

现在 这一工作流程中比较 复杂的部分之一 是创建促销优惠签名 至少在我们发布 App Store Server Library 之前是这样 让我来解释一下使用 App Store Server Library 的 签名创建过程

这是创建促销优惠签名的代码

首先 我实例化一个 PromotionalOfferSignatureCreator

传入 App 的私钥、keyId 和 bundleId 这些值将用于签署促销优惠签名 从而防止顾客在未经我同意的情况下 兑换促销优惠

接下来 我为优惠指定 productId 和优惠标识符 并为顾客指定 app_account_token 我创建了一个 nonce 并记录了当前时间戳 nonce 使得 App Store 能够防止优惠被多次兑换

我将这些参数 传递给 signatureCreator 然后接收一个 Base64 编码的签名 这个签名随后可以发送到顾客的设备 这就是使用 App Store Server Library 签署促销优惠的方法 现在 你可能想知道如何决定 向哪些人提供这些优惠 Ian 我想你一定有一些最新消息 可以分享对吗 是的 促销优惠需要考虑很多因素 包括创建什么类型的优惠 以及谁应该收到这些优惠 我们希望你尽可能多地掌握 有关订阅和优惠的信息 从而为你的业务和顾客 做出更好的决策

为此 2023 年底 在我们的服务器 API 和设备端通过 StoreKit 提供 的交易数据中 我们添加了一些新字段 新的价格和货币字段会指示 顾客进行购买时所显示的价格和货币 包括所应用的任何优惠 使用这些字段时 请记住 App Store Connect 报告 是财务和会计目的的真实来源 如果购买应用了优惠 那么新的 offerDiscountType 字段 可指示这个优惠的支付模式 即 FREE_TRIAL、PAY_UP_FRONT 或 PAY_AS_YOU_GO

这是一个订阅购买的 解码交易信息示例 新的价格和货币字段 显示购买时产品的显示价格 价格以货币的毫为单位 在本例中 4990 表示价格为 使用美元计价的四美元九十九美分

我们可以参考现有的 offerIdentifier 和 offerType 字段 了解用户兑换了哪项优惠 以及优惠的类型是什么 现在 新的 offerDiscountType 字段 表明这是一个“PAY_UP_FRONT”优惠

这些字段是了解不同时间 App 内购买的价格点的 重要参考点 现在 你可以查看 顾客的交易历史记录 并了解他们支付的价格 即使产品价格已发生变化也无妨

这是以订阅购买为例 说明新字段 是如何工作的 如果查看初始期间的交易信息 就会发现这次购买 是“PAY_UP_FRONT”优惠的一部分 交易的显示价格是 4.99 美元

在两个月促销期结束时 订阅会续订 顾客现在的正常价格为 9.99 美元

我们的 API 还为顾客的 每个订阅提供续订信息 这样你就可以了解 下次订阅自动续期时 会发生什么

我很高兴告诉大家 续订信息中现在也有三个新字段 分别是 renewalPrice、currency 和 offerDiscountType 这些新字段将帮助你了解 下次续订订阅时 适用的 预期显示价格和优惠支付模式

这是一个解码的订阅续订信息示例

renewalPrice 和 currency 字段 表明 App Store 服务器 预计下次续订购买 的显示价格为 8.99 美元

现有的 offerIdentifier 和 offerType 字段 表示 App Store 服务器预计 下次续订购买时应用的 优惠和优惠类型

现在 新的 offerDiscountType 字段 表示 App Store 服务器 预计续订购买是 “PAY_AS_YOU_GO”优惠的一部分

回顾一下我们的预付优惠示例 我们就能明白这些字段的工作原理 在初始促销期 续订信息包含即将到来的 正常期的信息 你可以看到续订时 将适用 9.99 美元的全价

第一次续订后 续订信息反映了 第二次续订时的情况 由于顾客现在支付的是正常订阅价格 所以字段保持不变

现在我将介绍一个 “PAY_AS_YOU_GO”的例子 在初始促销期间 续订信息反映的是 第一次续订时的购买情况 offerDiscountType 字段表明 下次购买仍将是 “PAY_AS_YOU_GO”优惠的一部分 续订价格为 2.99 美元 其中包括优惠折扣

第一次续订后 续订信息包含有关第二次续订的信息 renewalPrice 表明 订阅将恢复为 4.99 美元的正常价格

第二次续订后 续订信息保持不变 针对性促销优惠是吸引和留住 顾客订阅产品的有力工具 借助 App Store 服务器 API 提供的数据 你就可以根据自己的具体需求 为这些促销优惠设置 服务器端资格逻辑 例如 在向用户宣传优惠之前 你可以检查他们以前是否 在你的 App 中兑换过优惠 或者对于那些只购买过 低价产品的顾客 你可以创建一个优惠 让他们在有限的时间内 以优惠的价格试用高端产品

希望我们新增的字段能对你 制定优惠策略有所帮助 现在 我来简要回顾一下 今天讲座分享的新功能 新的 ONE_TIME_CHARGE 通知 是针对一次性购买发送的 因此现在你可以 使用 App Store 服务器通知 来追踪你 App 中的 每一次 App 内购买

CONSUMPTION_REQUEST 通知 现在会针对自动续期订阅 和消耗型项目提交的退款请求发送 这些通知现在包括新的 ConsumptionRequestReason 字段

使用这个字段和其他服务器端数据 你现在可以在调用 Send Consumption Information 端点时 表达自己对于同意还是 拒绝退款的偏好

新更新的 Get Transaction History 端点 会返回特定顾客在 App 中进行的 每一次购买的交易 因此你可以按需检索全面的数据

最后 price、currency 和 offerDiscountType 等新字段 可以让你更深入地了解订阅和交易 我的分享就是这些 Alex 你最后还有什么要说的吗 是的 我们很想听听大家 对今天分享的功能给出的反馈 以及你希望 App Store 服务器 下一步提供哪些功能 如果你对 App Store 服务器 有功能要求或反馈 请通过“反馈助理”告诉我们 提醒一下 我们在今天的讲座中 使用的 App Store Server Library 是开源的 欢迎加入 GitHub 提交问题 作出贡献 有关 App Store 服务器的 更多信息 请观看往年的讲座 感谢大家观看