StoreKit 2 服务端指南：使用 App Store Server API 管理 iOS 内购与订阅

Apple 在 WWDC 2021 上发布了新版 StoreKit 2，这是 iOS 中用于管理应用内购买的框架。随着订阅功能和内购应用的普及，StoreKit 2 的推出显著简化了应用内购买功能的集成过程。本文将详细介绍如何在服务端使用 StoreKit 2，并借助 App Store Server API 实现相关功能。

请求认证

在当前 JSON Web Token（JWT）标准进行认证，增强了安全性和灵活性。

密钥创建

首先，您需要创建一个私钥用于授权请求。具体步骤如下：

打开 App Store Connect，进入“用户与访问权限”页面。
选择“密钥”标签页，创建一个应用内购买类型的密钥并下载。
记录密钥 ID，可在 App Store Connect API 标签页的 Issue ID 旁复制该 ID。

令牌生成

接下来需要生成用于请求授权的令牌。以下是一个 Python 示例实现：

令牌的有效期最长可设置为 60 分钟，在此时间范围内可以重复使用，无需为每个请求重新生成。

签名交易

新版 API 中，所有交易均以 JSON Web Signature（JWS）格式返回。JWS 是由三部分组成的字符串，使用点号分隔：

Base64 编码的头部。
交易负载数据。
签名。

交易头部

头部包含用于验证交易真实性的信息，例如加密算法（Alg）和证书链（x5c）。

交易负载数据

Apple 扩展了交易数据格式，使其更易于处理。以下是一些关键更新：

新增字段 appAccountToken：用于标识系统用户 ID，需在移动应用发起购买交易时设置。此字段便于追踪用户的购买行为。
优惠相关字段：
- intro offer（新用户优惠）：适用于无有效订阅或订阅已过期的用户。
- promo offer（促销优惠）：适用于当前或已过期的订阅。
- offerIdentifier：包含已使用优惠的 ID，便于服务端追踪优惠使用情况。
新增字段 inAppOwnershipType：区分用户是直接购买还是通过家庭共享获取产品，可能值包括：
- PURCHASED（已购买）
- FAMILY_SHARED（家庭共享）
新增字段 transactionType：表示交易类型，可能值包括：
- 自动续订订阅
- 非消耗型
- 消耗型
- 非自动续订订阅
字段重命名：
- cancellation_date 和 cancellation_reason 更名为 revocationDate 和 revocationReason。
统一格式：
- 所有返回字段采用 camelCase 格式。
- 日期以 Unix 时间戳（毫秒级）显示。

用户订阅状态

要检查用户当前的订阅状态，可以向以下 URL 发送 GET 请求：

https://api.storekit.itunes.apple.com/inApps/v1/subscriptions/{originalTransactionId}

其中，originalTransactionId 是用户任意交易链的 ID。响应中包含各订阅组的状态信息。

status 字段：显示当前订阅状态，可能值包括：
- 1：订阅有效，用户应获得付费功能访问权限。
SignedTransactionInfo 字段：包含交易链中最后一笔交易的详细信息。

订阅续订信息

SignedRenewalInfo 字段提供订阅续订信息，可用于预测下个计费周期的状态。例如，当检测到用户关闭自动续订时，可以推荐其他订阅方案或提供促销优惠。

用户交易历史

要获取用户的交易历史，可向以下 URL 发送 GET 请求：

https://api.storekit.itunes.apple.com/inApps/v1/history/{originalTransactionId}

响应按时间排序返回交易记录。
单次请求最多返回 20 条记录。
如果用户有更多交易，hasMore 标志将为 true，需发送包含修订后 GET 参数的相同请求以获取下一页数据。

服务器交易通知

服务器通知可实时获取购买、续订、支付问题等信息，帮助构建更精准的分析指标并简化订阅状态管理。

V2 版通知的改进

相比 V1 版，V2 版通知针对每个用户操作仅发送单条通知，显著简化了处理流程。新增事件类型包括：

OFFER_REDEEMED（优惠已兑换）
EXPIRED（订阅已过期）
GRACE_PERIOD_EXPIRED（宽限期已过期）

此外，SUBSCRIBED 和 PRICE_INCREASE 事件也进行了优化。

通知类型

每种用户操作都有对应的专属通知类型，单条通知即可明确事件性质。

沙箱环境使用

测试购买交易时需使用沙箱环境 URL：

https://api.storekit-sandbox.itunes.apple.com

目前尚无新版服务器通知的测试环境。
App Store Connect 支持清除沙箱用户购买历史，无需新建测试账号。

结论

Apple 通过 StoreKit 2 显著改进了服务端处理订阅和应用内购买的体验。以下功能尤为实用：

官方支持促销和优惠码，便于分析和追踪用户行为。
内置分析功能帮助快速掌握应用关键指标。

迁移到新 API 并不复杂，只需获取每笔收据的 originalTransactionId 即可。通过这些改进，开发者可以更高效地管理应用内购买和订阅功能。

原文链接: https://adapty.io/vi/blog/storekit-2/