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

一. StoreKit 2 简介

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

二. 请求认证

在当前 API 版本中，认证请求需使用共享密钥（Shared Secret），可在 App Store Connect 获取。新版 API 则采用 JSON Web Token（JWT）标准进行认证，增强了安全性和灵活性。

1. 密钥创建

创建私钥用于授权请求，具体步骤如下：

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

2. 令牌生成

生成用于请求授权的 JWT 令牌。示例 Python 实现如下：

令牌有效期最长可设置为 60 分钟，可在此期间重复使用，无需每次请求都生成新令牌。

三. 签名交易

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

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

1. 交易头部

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

2. 交易负载数据

Apple 扩展了交易数据格式，主要更新如下：

a. 新增字段

appAccountToken：标识系统用户 ID，便于追踪购买行为。
优惠相关字段：
- intro offer（新用户优惠）
- promo offer（促销优惠）
- offerIdentifier：记录已使用优惠 ID，便于服务端追踪。
inAppOwnershipType：区分用户是直接购买还是家庭共享获取，可能值包括：
- PURCHASED（已购买）
- FAMILY_SHARED（家庭共享）
transactionType：交易类型，可能值包括：
- 自动续订订阅
- 非消耗型
- 消耗型
- 非自动续订订阅

b. 字段重命名

cancellation_date → revocationDate
cancellation_reason → revocationReason

c. 格式统一

所有返回字段采用 camelCase。
日期以 Unix 时间戳（毫秒）显示。

四. 用户订阅状态

检查用户订阅状态的请求 URL：

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

originalTransactionId：用户任意交易链的 ID。
响应包含订阅组状态信息：
- status：当前订阅状态，例如 1 表示有效。
- SignedTransactionInfo：最后一笔交易的详细信息。

1. 订阅续订信息

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

五. 用户交易历史

获取用户交易历史的 URL：

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

响应按时间排序返回交易记录。
单次最多返回 20 条记录。
若用户交易超过 20 条，hasMore 为 true，需发送分页请求获取下一页数据。

六. 服务器交易通知

服务器通知可实时获取购买、续订、支付问题等信息，便于分析和订阅管理。

1. V2 版通知改进

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

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

此外，SUBSCRIBED 和 PRICE_INCREASE 事件优化处理。

2. 通知类型

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

七. 沙箱环境使用

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

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

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

八. 结论

StoreKit 2 显著提升了服务端处理订阅和应用内购买的体验，主要优势：

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

迁移到新 API 简单，仅需获取每笔收据的 originalTransactionId 即可。借助这些改进，开发者可更高效管理应用内购买和订阅功能。

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