以下是你提供的 StoreKit 2
Transaction
JSON 各字段含义解析:
字段 | 类型 | 含义 |
---|---|---|
transactionId | String |
本次交易的唯一标识符(Apple 服务器生成)。每次用户购买或续订时都不同。 |
originalTransactionId | String |
原始交易 ID。对于自动续订订阅,首次购买时生成,后续续订会复用该 ID,用来关联同一订阅链。 |
webOrderLineItemId | String |
用于 App Store 后端报表的行项目 ID,可用于跨平台(如 Web、iOS)或者后台对账。 |
bundleId | String |
App 的 Bundle Identifier,表示是哪一个应用发起了这笔交易。 |
productId | String |
购买的内购商品标识符(Product Identifier),即你在 App Store Connect 中配置的 ID。 |
subscriptionGroupIdentifier | String |
订阅组 ID,属于同一组的订阅产品互斥,同组内同一用户只能激活一个订阅方案。 |
purchaseDate | Number |
本次交易的购买时间,Unix 毫秒数(UTC)。例如 1752148768000 表示 2025‑12‑10 08:19:28 UTC。 |
originalPurchaseDate | Number |
原始购买时间,Unix 毫秒数。对于续订,将是首次购买的时间。 |
expiresDate | Number |
订阅或试用期的到期时间,Unix 毫秒数。到期后如果未续订,就视为订阅结束。 |
quantity | Int |
购买的数量。对于订阅通常为 1 ,消费型商品可能大于 1。 |
type | String |
内购类型,此处 "Auto-Renewable Subscription" 表示自动续订订阅;其他可能值还有 "Non-Consumable" 、"Consumable" 、"Non-Renewing Subscription" 。 |
deviceVerification | String |
Base64 编码的设备验证令牌,用于防篡改校验,可发送到服务器并与 Apple 校验。 |
deviceVerificationNonce | String |
随机生成的唯一值,与 deviceVerification 配合使用,保证验证请求的唯一性。 |
inAppOwnershipType | String |
购买归属类型: |
• "PURCHASED" :用户已购买 |
||
• "FAMILY_SHARED" :通过家庭共享获得 |
||
• "UNKNOWN" :未知或无权访问 |
||
signedDate | Number |
交易数据在设备上签名的时间,Unix 毫秒数,用于校验数据新鲜度。 |
environment | String |
交易环境: |
• "Sandbox" :沙盒测试 |
||
• "Production" :正式环境 |
||
transactionReason | String |
触发此次交易的原因: |
• "PURCHASE" :用户主动购买 |
||
• "RENEWAL" :自动续订 |
||
• "INTERACTIVE_RENEWAL" :用户在订阅管理界面手动续订等 |
||
storefront | String |
App Store 区域码(ISO 国家/地区简码),如 "CHN" 表示中国大陆。 |
storefrontId | String |
App Store 地区标识符,用于更精细的区域分发。 |
price | Int |
以最小货币单位表示的价格。例如 59000 表示 ¥590.00(CNY)。 |
currency | String |
货币代码,如 "CNY" 、"USD" 。 |
appTransactionId | String |
App 级别的交易 ID,可用于客户端内部追踪。同一个 transactionId ,可能在不同平台(iOS/macOS)下有不同 appTransactionId 。 |
💡 小贴士
- 时间字段 (
purchaseDate
、expiresDate
等) 都是以毫秒为单位的 Unix 时间戳,需根据时区转换展示给用户。 - 服务器校验 :通常你会将
deviceVerification
+deviceVerificationNonce
或整个 JSON 发送到后台,由后台调用 Apple 验证接口进行二次校验,确保证据未被篡改。 - 续订关联 :
originalTransactionId
贯穿同一次订阅链,方便后台做续订统计和账单归因。
以上字段含义能帮助你在客户端和后台实现精确的订阅状态管理与数据对账。 🚀
type 字段一般都有什么样是值
type
字段对应了内购项目的种类,在 StoreKit 2 的 Transaction
JSON 中,你常见到以下几种值:
Consumable
消耗型商品,一次购买后即"用完",可重复购买(如游戏内金币、道具)。Non-Consumable
非消耗型商品,一次购买永久有效(如解锁专业版功能、永久皮肤)。Non-Renewing Subscription
非自动续期订阅,到期后需要用户手动续订(如半年课程访问权限)。Auto-Renewable Subscription
自动续期订阅,到期后由系统自动续费(如月度/年度会员)。
transactionReason 一般都有什么值,含义什么
transactionReason
表示触发此次交易的原因,在 StoreKit 2 的 Transaction
JSON 中,常见的取值有三种:
PURCHASE
用户主动发起的首次购买或在 App 内直接购买订阅时产生的交易。Apple DeveloperRENEWAL
自动续订订阅到期后,由系统在后台自动发起的续订交易。Apple DeveloperINTERACTIVE_RENEWAL
用户在 App Store 的订阅设置界面(或通过 App 内提供的入口)主动续订已过期或已取消的订阅时产生的交易。Stack Overflow
📌 小贴士
- 这三种原因涵盖了 用户购买 、系统自动续订 和 用户手动续订 的主要场景。
- 当你在
Transaction.updates
或者通过 App Store Server API 查询到交易 JSON 时,可以根据transactionReason
字段判断当前是首次购买、自动续订,还是交互式续订,以便做不同的业务逻辑处理(如提示用户"已续订"或"请手动续订")。