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

大家好 我叫 Riyaz 是 App Store 服务器团队的工程师 本次讲座 我们将深入研究用于 App 内购买 项目的 App Store Server API 我将展示最近的更新如何简化 和改进 App 服务器的工作 我们先来了解一些 App 服务器 执行的主要工作 在本讲座中 我将重点介绍 三项关键工作

第一项是管理 App 内购买项目 这项任务涉及将交易数据 与顾客账户关联 这样你的 App 就可以 顺畅地交付内容和服务

第二项是签名请求 这需要生成签名 授权你的服务器 向 App Store 发送请求

第三项是参与退款决策流程 通过提供与购买相关的消费数据 你的服务器可以 帮助 App Store 正确做出退款决策 App 服务器有很多关键工作 这些就是其中的三项 接下来 我会讲解 App Store Server API 的更新 如何改进这些工作 要讲的内容很多 让我们一起进入正题吧 首先我将介绍交易标识符的更新 这项更新可让你 更好地管理 App 内购买项目 然后我将介绍生成签名方面的改进 这可以简化服务器签名请求的过程 最后我将介绍一些增强功能 它们可以让你更简单地 参与退款流程

我们来深入详细地了解一下 首先是管理 App 内购买项目 管理 App 内购买项目的一大作用是 会在你的系统上 有效地处理顾客账户

通常会在你的系统上为每位顾客 分配一个唯一的账户 ID 将顾客账户与 App Store 交易 明确地关联起来 这种关联对于准确交付内容和 个性化用户体验来说 至关重要 App Store 通过三种关键数据结构 提供 App 内购买项目数据： AppTransaction、 JWSTransaction 和 JWSRenewalInfo

首先我将重点介绍 JWSTransaction 稍后再来介绍其他类型

顾客进行 App 内购买时 App Store 会提供一个 签名的交易对象 JWSTransaction 会在服务器上 提交这个已签名的交易 可以用 App Store Server Library 有效地验证和解码

这里是已解码的 signedTransactionInfo 的示例

前几个字段包含 与 App 相关的重要信息 以及 App 内产品的类型 接下来是有关购买的元数据 包括数量、价格和货币 如果顾客使用了优惠 JWSTransaction 还会包含 offerType、offerIdentifier 和 offerDiscountType 字段 我们最近添加了 一个新字段 offerPeriod 它会使用 ISO 8601 持续时间格式 指示所用优惠的持续时间 JWSRenewalInfo 中 也包含了这个字段 告知你优惠的持续时间 将覆盖下次续订

然后是交易标识符 transactionId 是交易的唯一标识符 交易包括 App 内购买项目、 恢复购买或续订等 在这个例子中 它是续订的交易 ID

originalTransactionId 是 首次购买的交易 ID 它可以帮助你准确识别 自动续期订阅 因为所有续订的 首次交易 ID 都相同

最后是 appAccountToken 这是你在 App 中设置的 UUID 是在顾客进行 App 内购买时 使用StoreKit 生成的 这个字段可以在你的系统上 将购买与顾客账户关联起来 为了更轻松地获取 appAccountToken 用于续订 我们在 JWSRenewalInfo 中 加入了这个字段 这将帮助你顺畅地将顾客账户 与他们最近的续订交易关联起来 接下来我将解释它是如何工作的 首先会在服务器上生成一个 UUID 并将这个值与顾客账户相关联 然后你的服务器会将这个值传递给 你的 App 接下来 StoreKit 会在顾客进行 App 内购买时 设置 appAccountToken 我们建议对同一顾客账户 进行的所有 App 内购买 都使用相同的 appAccountToken 值 App Store 服务器会返回 相同的 appAccountToken 值 这个值就在 JWS 交易和续订信息中 之前只能在顾客进行 App 内购买时 设置 appAccountToken 但顾客也可能在 App 之外进行购买 例如兑换优惠代码时 或在 App Store 推广中 进行购买时 为了让你可以在这种情况下 更灵活地设置 appAccountToken 我们新增了一个服务器端点 可以用 Set App Account Token 端点为交易设置 新的 appAccountToken 或更新现有的 appAccountToken 这个端点可以用于所有产品类型 包括 过去的一次性购买 例如消耗型项目、 非消耗型项目、非续期订阅 以及每次新近的自动续期订阅 对于自动续期订阅 使用这个端点设置的 appAccountToken 会在未来的续订中延用 包括升级或降级

Set App Account Token 端点 非常有用 如果顾客在 App 之外完成交易 例如兑换优惠代码 对于这类购买 从前无法 设置 appAccountToken 字段 因为 StoreKit 并未参与其中 此外 你还可以修复 appAccountToken 与顾客账户 关联不一致的问题 例如 当系统中的账户所有权 改变时 接下来我要介绍一下这个端点 它是 App Store Server API 的 一部分

这里的例子展示了如何使用 Set App Account Token 端点 在路径中提供 originalTransactionId 这个值可以标识一次性购买交易 也可以标识你要设置 appAccountToken 的订阅

在请求正文中 为 appAccountToken 设置 所需的 UUID 值 Set App Account Token 端点 提供的 appAccountToken 将覆盖之前为这个交易 设置的所有 appAccountToken appAccountToken 以及其他 交易标识符 如 transactionId 和 originalTransactionId 可用于将顾客账户 与 App Store 交易关联起来 我接下来会简单 介绍一下这些标识符 App Store 是 transactionId 和 originalTransactionId 的来源 而你要负责生成 appAccountToken 并把它和 App Store 交易关联起来 transactionId 可用于 标识特定的一次购买 而 originalTransactionId 非常适合统一管理 一个订阅产品的所有自动续期订阅 也适合用于检查订阅状态 appAccountToken 可将 顾客的账户信息 与他们的 App 内购买行为关联起来 如果你的 App 支持家人共享 请注意 appAccountToken 不能用于家庭共享交易 transactionId 和 originalTransactionId 在 JWSTransaction 和 JWSRenewalInfo 中都有 只有用 StoreKit 或新的 Set App Account Token 端点 为购买设置了 appAccountToken 才会存在这个值

当顾客下载你的 App 时 会通过 StoreKit 生成 AppTransaction 对象 它会提供重要的 App 下载信息 因为 transactionId、 originalTransactionId 和 appAccountToken 都针对具体的 App 内购买行为 所以它们不会包括 在 AppTransaction 对象中 但有时必须要为一次 App 下载 提供唯一的标识符 这是为了在 App 安装时 解锁内容之类的目的 因此我们在 AppTransaction 对象 中新增了一个 名为 appTransactionId 的字段 以便应对之前讲的情况 appTransactionId 是全局唯一标识符 每个 App 中的每个 Apple 账户 只有一个 对于家人共享 每个家庭成员 都有一个唯一的 appTransactionId 根据设计 一个 Apple 账户在一个 App 中只有一个 appTransactionId 无论是重新下载、退款、重复购买 或改变店面 这个值都不会变 同一位顾客在你的 App 中进行的 所有 App 内购买都会包含 这个 appTransactionId 这提供了更大的灵活性 让你可以将顾客账户 与所有 App Store 交易相关联 接下来我将解释它是如何工作的 这里是一种方法 可以用 appTransactionId 将顾客账户与 App Store 交易关联起来 首先 顾客下载你的 App 时 在你的系统中 用 AppTransaction 对象中的 appTransactionId 关联顾客账户 在服务器上获取 AppTransaction 对象的一种方法 是从你的 App 发送这个信息 顾客进行 App 内购买时 JWSTransaction 和 JWSRenewalInfo 都包含相同的 appTransactionId 因此你只需关联一次 然后就能在所有 App Store 交易对象中重复使用 由于 appTransactionId 存在于 所有 App Store 交易对象中 因此能为你的 App 解锁一些 很有价值的用例 例如确定两项不同的 订阅购买项目 是否属于同一个顾客账户 举个例子 假设你的 App 提供两种订阅产品： 一个是每月收费的体育时事月刊 另一个是每年收费的赛季订阅 用来观看赛事直播 你如何确定一个顾客账户 是否同时拥有这两项订阅？

虽然每项订阅的 transactionId 和 originalTransactionId 都不同 但它们的 appTransactionId 是相同的 你可以利用这个字段在 App 启动时就应用个性化设置 例如恢复 App 内购买项目 此外你还可以将 appTransactionId 作为交易 ID 用于常用的 App Store Server API 端点 例如 Get Transaction History、 Get All Subscription Statuses 等 今天 我很高兴能向大家 介绍一个新的端点 它让你可以使用服务器端点 获取 AppTransaction 对象 借助新的 Get App Transaction Info 端点 你可以直接在服务器上 获取 App 下载信息 而不必依赖设备 这在以前是无法做到的 你可以使用 AppTransaction 对象 查看重要的 App 下载信息 例如 App 版本、平台和环境 你可以通过这些信息了解 App 在不同商业模式下 性能如何 请记住 这个端点不会 返回与设备相关的详细信息 例如设备验证 要获取这些信息 你仍要依赖由 App 提供 的 AppTransaction 对象 接下来我来介绍一下这个端点 它属于 App Store Server API

这里的例子将展示如何使用 Get App Transaction Info 端点 你可以在路径中提供 任意交易标识符 如 originalTransactionId、 transactionId 或 appTransactionId 返回的信息将包含 JWS signedAppTransactionInfo 你可以用 App Store Server Library 等方法 来解码 signedAppTransactionInfo Get App Transaction Info 端点 将于今年晚些时候推出 现在我来比较一下 appTransactionId 和我之前展示的其他交易标识符 App Store 会生成 appTransactionId、 transactionId 和 originalTransactionId

你可以使用 appTransactionId 来唯一标识 App 下载 并将顾客的后续购买 与这个下载相关联 appTransactionId 在所有 App Store 交易对象中都相同 你可以将 appTransactionId 用于家人共享交易 如果你的 App 支持家人共享的话 我们强烈推荐 appTransactionId 因为这种标识符能满足 你的所有需求 它简化了 App 内购买项目的管理 可以将这类购买与 服务器上的顾客账户相关联 现在 我们来看看我们对签名请求 所做的一些重大改进 第一步是在你的服务器上 创建一条 JWS 字符串 JWS 是 JSON Web Signature 的缩写 然后使用专用密钥 签名这条字符串 专用密钥是从 App Store Connect 下载的

之后将这个签名字符串 发送到 App 并使用 StoreKit 调用需要签名的函数

然后 StoreKit 将签名字符串 发送到 App Store 服务器 以前 根据具体用例 你要用不同格式来签名 具体格式要遵循 App Store 服务器的要求 现在 我们为所有用例 统一了签名请求 都使用 JWS 签名格式 这意味着你现在可以在需要的 StoreKit 调用中使用这种格式 包括生成促销优惠签名等函数 现在你可以使用 JWS 签名格式 为促销优惠签名 这种新的签名方法 可以代替从前的促销优惠签名 为了让你更灵活地处理 推介促销优惠 我们最近推出了一个 新的 JWS 推介促销优惠签名 借助这项功能 你可以为 每次交易、每位用户 设定个性化的 推介促销优惠参与条件 从而更好地控制 顾客能在 App Store 中 兑换多少推介促销优惠 你还能用 Advanced Commerce API 发送已签名的 JWS App 内请求 如需了解更多信息 请访问开发者文档 现在我将展示如何在 你的服务器上创建 JWS 促销优惠签名 如何使用 StoreKit 提供的 促销优惠签名 留住 App 现有的订阅用户 或赢回流失的订阅用户 这里是使用 App Store Server Library 创建促销优惠签名的示例 在这个例子中 我用的是 Java 首先 我要实例化一个类 PromotionalOfferV2SignatureCreator 这要用到专用密钥、keyId、 issuerId 和 App 的 bundleId 你可以在 App Store Connect 上 找到密钥、keyId 和 issuerId

这些值用于签名 防止顾客未经开发者同意 就兑换促销优惠

接下来指定 transactionId 你可以提供任何 属于顾客的交易标识符 包括 appTransactionId

如果你只想让某位顾客享受优惠 就请提供 transactionId 如果没有这个需要 就可以跳过这个字段

然后提供 productId 和 offerId 我已经预先在 App Store Connect 中配置了 这个 ID 表示的产品

最后将 productId、 offerId 和 transactionId 传递给 createSignature 函数 请注意 新版签名 比老版本更简单 输入更少 你在多种用例里 都可以简单地使用 统一的 JWS 签名格式 来签名请求 即使你提供了优惠 有时顾客也可能会 退出交易 要求退款 个中原因你往往无法掌控 例如账单问题 或不小心买错了 在这种情况下 我来展示一下如何 参与退款决策流程 首先 我要讲一下这样做的好处 你应该考虑参与退款决策 因为你了解顾客的产品消费情况 例如你在 App 上提供了消耗型项目 那么你的服务器上就记录了顾客的 这款消耗品是否使用 剩余多少 这有助于在顾客提出 退款请求后提高他们的满意度

当顾客请求退款时 App Store 会向你的服务器发送 CONSUMPTION_REQUEST 通知 为了给退款决策流程 提供必要信息 你可以使用 Send Consumption Information 端点 响应这条通知

我很高兴与大家分享 我们推出了经过改进的新版 Send Consumption Information V2 端点

从本质上讲 新版端点更易于集成 因为与旧版相比 我们大大减少了 你要提供的输入数量 新端点还支持选择按比例退款 以便更好地应对顾客 部分消耗了所购产品的情况 老版端点仅支持消耗型项目 和自动续期订阅 而新版扩大了支持范围 涵盖所有产品类型 包括非消耗型项目和非续期订阅

如果你已经在使用 V1 端点 请注意 这个端点现已弃用 但仍将继续接受请求 如果你还没用过 Send Consumption Information 端点 我们建议搭配使用新版 V2 端点 和 App Store Server Library 现在 我将演示如何使用 Send Consumption Information V2 端点 假设顾客购买了一种消耗型项目 然后又申请了退款 CONSUMPTION_REQUEST 通知 已发送到你的服务器 这里的示例展示了如何使用 Send Consumption Information V2 端点来响应这条通知

在路径中提供 transactionId 你可以在 CONSUMPTION_REQUEST 通知中找到这个值

新版端点总共支持五个输入字段 相比老版的十二个来说减少了很多 五个输入字段中 有三个必填字段 以及两个选填字段 我们大幅减少了字段 这是为了让你更简单地 参与退款决策 将 customerConsented 字段 设为 true 前提是 顾客同意将与退款申请有关的 消费数据发送给 App Store 包括你在 ConsumptionRequestV2 正文中提供的所有数据 如果顾客不同意 就不要响应 CONSUMPTION_REQUEST 通知 如果调用了端点 而这个字段设为 false 请求就会被拒绝 使用 sampleContentProvided 说明 是否在顾客购买产品之前 提供了试用样品 如果你已向顾客成功交付了内容 就在 deliveryStatus 中 填入 DELIVERED 反之 则相应地填入 UNDELIVERED 状态

你可以选择希望进行哪类退款 除了之前就支持的全额退款 或不退款外 你现在还可以选择 使用 GRANT_PRORATED 值 设置按比例退款 如果你不想选择这种退款 就不要设置这个字段 consumptionPercentage 以千分之一表示产品的消耗量

此处 25,000 的数值表示 消耗品已消耗了 25% Send Consumption Information V2 端点将于今年晚些时候推出 现在 让我们深入了解一下 新的按比例退款选项 这个选项在新版 V2 端点中提供 如果消耗型项目可以部分消耗 就应考虑选择按比例退款

按比例退款选项 允许你说明消耗量 以便 App Store 准许 退回适当的金额

如果你选择了按比例退款 就必须 指明 consumptionPercentage 值 这适用于消耗型项目、非消耗型 项目和非续期订阅产品类型 这样 App Store 才能准许 退回金额准确的款项 请注意 对于自动续期订阅 App Store 会自动计算 consumptionPercentage 值 依据是顾客所购订阅的剩余时间 你提交的消耗数据 帮助 App Store 决定 是全额退款、 按比例退款 还是拒绝退款 REFUND 或 REFUND_DECLINED 通知会告知你决策结果 如果你收到 REFUND_DECLINED 通知 无需采取任何操作 但是如果收到了 REFUND 通知 就要采取适当的操作 这是一个 REFUND 通知的示例 现在 通过新的 refundPercentage 字段 你可以了解 App Store 准许退回多少款项 在这个例子中 准许退回 75% 的款项 这样你就可以对已消耗的产品 采取适当的操作

使用这个字段时 请记住 所有财会工作 都要以 App Store Connect 提供的数据为可靠依据 通过新的 revocationType 字段 你还可以了解 撤销的类型 这个字段的值可能是 REFUND_FULL、 REFUND_PRORATED 或 FAMILY_REVOKE 由于这个例子里是 消耗型项目的退款 可能的值为 REFUND_FULL 和 REFUND_PRORATED 如果是全额退款或撤销家人共享 你就要立即撤销 对服务器上内容的访问权限 对于 REFUND_PRORATED 要按照退款 比例 撤销对剩余内容的访问权限 接下来 我将展示 如何在你的服务器上 处理按比例退款的通知 对于消耗型项目 或非续期订阅产品 你要使用 refundPercentage 字段来计算 应撤销顾客账户 访问权限的内容比例 例如 如果顾客购买了虚拟货币 就要根据退款金额 扣除剩余的虚拟货币 对于自动续期订阅 要按照处理全额退款的方式 处理按比例退款 检查当前的订阅状态 并采取适当的措施 我推荐使用新的 Send Consumption Information V2 端点 来参与退款决策流程 因为它更易用 功能也更强大 今天我们讲了很多！ 我们来快速回顾一下 我展示了各种交易标识符 介绍了 appTransactionId 这种交易标识符用途很广 然后 我介绍了 统一的 JWS 签名格式 最后 我展示了 参与退款决策是多么简单 结束之前 我还要分享 一些有用的后续行动 如果你已经为开源 App Store Server Library 贡献了一份力 非常感谢！ 如果还没有 请访问 我们的 GitHub 页面 了解如何为 App Store 社区 做出贡献 支持社区发展 每当推出新功能 我们都非常期待收到你的反馈 请使用“反馈助理”向 App Store 服务器团队 提交你对功能的要求和反馈 要进一步了解我们对 StoreKit 所做的更新 请观看 WWDC25 讲座“StoreKit 和 App 内购买项目的新功能” 此外 还请观看 WWDC24 讲座 “探索适用于 App 内购买项目的 App Store Server API” 进一步了解 App Store 服务器 感谢大家观看 下期再见！