亲宝软件园·资讯

展开

iOS StoreKit 2 新特性

字节跳动技术团队 人气:0

一、背景

2021 年 WWDC,在 iOS 15 系统上推出了一个新的 StoreKit 2 库,该库采用了完全新的 API 来解决应用内购买问题。

二、物料

名词解释 
IAPIn-App Purchase:应用内购买 
StoreKit 1原始的应用内购买 APIChoosing a StoreKit API for In-App Purchase
StoreKit 2应用内购买 APIChoosing a StoreKit API for In-App Purchase

三、StoreKit 1 存在的问题

不能。只能苹果处理退款后发通知给我们的服务器,告知发生了一笔退款

不能。系统没提供这种测试方式。

不能。

不支持使用苹果收据里的 orderID 去苹果服务器查询交易信息,没有提供这个 API(StoreKit 2 出来后支持去查询 StoreKit1 的交易了,developer.apple.com/documentati… )。

四、StoreKit v2 新特性

StoreKit 2 新特性主要包含三部分:

五、StoreKit 2 API

StoreKit 2 主要的更新有这几个:

5.1 只支持 Swift 开发

StoreKit 2 使用了 Swift 5.5 的新特性进行开发,完全修改了获取商品、发起交易、管理交易信息等接口 API 的实现方式。swift.org/blog/

例如获取商品方式语法不同:

原始获取商品方式

// 1. 请求商品
  SKProductsRequest *request = [[SKProductsRequest alloc] initWithProductIdentifiers:identifiers];
  request.delegate = pipoRequest;
  [request start];
// 2. 实现 SKProductsRequestDelegate
- (void)productsRequest:(SKProductsRequest *)request didReceiveResponse:(SKProductsResponse *)response
{
    // success
}
- (void)request:(SKRequest *)request didFailWithError:(NSError *)error API_AVAILABLE(ios(3.0), macos(10.7))
{
    // failed
}

新获取商品方式

// 获取商品
let products = try await Product.products(for: productIDs)
// 购买商品
func purchase(_ product: Product) async throws -> Transaction? {
    //Begin a purchase.
    let result = try await product.purchase()
    switch result {
    case .success(let verification):
      let transaction = try checkVerified(verification)
      //Deliver content to the user.
      await updatePurchasedIdentifiers(transaction)
      //Always finish a transaction.
      await transaction.finish()
      return transaction
    case .userCancelled, .pending:
      return nil
    default:
      return nil
    }
  }

5.2 新 API

5.2.1 Product

方便我们利用的字段:

举个例子:

某些 APP 会有会员订阅服务,那些服务会有 1 个月,3 个月,12 个月等的自动续期,同时还会有一些第一次购买的优惠,这个第一次购买的优惠就是首购优惠,并且这个优惠跟 Apple ID 挂钩,跟 APP 内自己的账号体系无关,例如小马哥旗下产品,自有的账号体系是 QQ 号 + 微信号,那么我们在之前是无法简单得判断你这个 Apple ID 是否享受过首购优惠了,毕竟用户可以有多个 QQ 号,或者多个 微信号,在弹出苹果的购买页面前,我们是不知道这个 Apple ID 有没有享受过首购优惠的,会对用户产生误解,我在上一个页面还告诉我首个月只要 18 块钱,实际支付的时候为什么要 25 元了 ? 这个对用户的购买意愿肉眼可见是有下降的。

现在我们就可以通过 isEligibleForIntroOffer 这个属性,轻松又方便得提前拿到这些信息,对已经享受过的Apple ID账号不展示这个优惠。

public static func products<Identifiers>(for identifiers: Identifiers) async throws -> [Product] where Identifiers : Collection, Identifiers.Element == String

appAccountToken 字段是由开发者创建的;关联到 App 里的用户账号;使用 UUID 格式;永久存储在 Transaction 信息里。

PS:这里的 appAccountToken 字段苹果的意思是用来存储用户账号信息的,但是应该也可以用来存储 orderID 相关的信息,需要将 orderID 转成 UUID 格式塞到 Transaction 信息内,方便处理补单、退款等操作。

public func purchase(options: Set<Product.PurchaseOption> = []) async throws -> Product.PurchaseResult
let uuid = Product.PurchaseOption.appAccountToken(UUID.init(uuidString: "uid")!)
// 发起一笔购买之后,直接等待苹果的返回结果,无需在paymenqueue中等待transaction状态的更新。
//使用sk2发起的购买的订单的信息,在sk1所有的回调接口都不会得到相应的transaction的更新状态
let result = try await product.purchase(options: [uuid])
// demo
func purchase(_ product: Product) async throws -> Transaction? {
    //Begin a purchase.
    let result = try await product.purchase()
    switch result {
    case .success(let verification):
      let transaction = try checkVerified(verification)
      //Deliver content to the user.
      await updatePurchasedIdentifiers(transaction)
      //Always finish a transaction.
      await transaction.finish()
      return transaction
    case .userCancelled, .pending:
      return nil
    default:
      return nil
    }
  }

func checkVerified<T>(_ result: VerificationResult<T>) throws -> T {
    //Check if the transaction passes StoreKit verification.
    switch result {
    case .unverified:
      //StoreKit has parsed the JWS but failed verification. Don't deliver content to the user.
      throw StoreError.failedVerification
    case .verified(let safe):
      //If the transaction is verified, unwrap and return it.
      return safe
    }
  }
func listenForTransactions() -> Task<Void, Error> {
    return Task.detached {
      //Iterate through any transactions which didn't come from a direct call to `purchase()`.
      for await result in Transaction.updates {
        do {
          let transaction = try self.checkVerified(result)
          //Deliver content to the user.
          await self.updatePurchasedIdentifiers(transaction)
          //Always finish a transaction.
          await transaction.finish()
        } catch {
          //StoreKit has a receipt it can read but it failed verification. Don't deliver content to the user.
          print("Transaction failed verification")
        }
      }
    }
  }

针对 transaction 的更新,这个监听是让我们监听:

5.2.2 Transaction History

提供了三个新的交易(Transcation)相关的 API:

根据可以购买的订阅商品、非消耗品可以过滤出已经购买过的商品。

extension Transaction {
  public static var all: Transaction.Transactions { get }
  public static var currentEntitlements: Transaction.Transactions { get }
  public static func currentEntitlement(for productID: String) async -> VerificationResult<Transaction>?
  public static func latest(for productID: String) async -> VerificationResult<Transaction>?
  public static var unfinished: Transaction.Transactions { get }
}
extension AppStore {
  public static func sync() async throws
}

5.2.3 Subscription status

订阅类型项目的状态,比如主动获取最新的交易、获取更新订阅的状态,获取更新订阅的信息等。其中获取更新订阅的信息,可以获取更新的状态、品项 id、如果过期的话,可以知道过期的原因。(比如用户取消、扣费失败、订阅正常过期等。)获取的所有数据都是 JWS 格式验证。

5.2.4 show manager subscriptions

可以直接唤起 App Store 里的管理订阅页面。

extension AppStore {
  @available(iOS 15.0, *)
  @available(macOS, unavailable)
  @available(watchOS, unavailable)
  @available(tvOS, unavailable)
  public static func showManageSubscriptions(in scene: UIWindowScene) async throws
}

5.2.5 request refund API

提供了新的发起退款 API,允许用户在开发者的 App 中直接进行退款申请。用户进行申请退款后,App 可以收到通知、另外苹果服务器也会通知开发者服务器。(沙盒环境也可进行退款测试了,但是 App Store 里还没开启这个功能。)

extension Transaction {
  public static func beginRefundRequest(for transactionID: UInt64, in scene: UIWindowScene) async throws -> Transaction.RefundRequestStatus
}

小结:

六、Server to Server

构建开发者服务器可以实现以下几个功能:

6.1 Validate status with receipts

服务器端在通过 /verifyReceipt 接口验证票据时,新 API 的数据结构也发生了变化。例如统一了购买时间、过期时间、原始购买时间格式,新增了 appAcountToken 字段、内购类型字段、退款时间、退款原因、促销优惠类型等。具体的可以参考 Manage in-app purchases on your server - WWDC21 - Videos - Apple Developer 视频,或者 Validating Receipts with the App Store | Apple Developer Documentation

6.2 Check status with APIs

新增了一些 API,可以主动去获取订阅状态、交易历史记录等等。具体可以参考这个文档:App Store Server API | Apple Developer Documentation

6.3 Track status with notifications

当订阅状态发生变化时,Apple server 会主动通知我们的服务器,告知发生了哪些变化。功能跟之前的版本一样,但是删除了一些状态,也新增了一些状态。

为了方便测试沙盒环境的退款通知,App Store 可以为沙盒环境单独设置一个 server URL 配置。

6.4 购买流程变化

例如第一次购买订阅类型商品时,购买成功后,Apple server 会主动通知 我们的 server,告知状态。此时我们的 server 可以不用再去 Apple server 那边验证了。及时以后想验证,也可通过 /inApps/v1/subscriptions 接口随时去验证。

续订、账单宽限期、用户退款等操作时除了可以接受苹果的通知外,也可以主动去请求苹果服务器,获取最新的状态。例如在自己服务器宕机或者因为某种原因导致没有接收到苹果的通知时,此时主动去请求苹果服务器获取交易历史记录,交易状态信息,就发挥出了巨大的作用。

6.5 服务器迁移升级到 JWS 格式

对于 StoreKit 2,苹果已经废弃了用 receipt 收据验证逻辑,只需要提供交易的 originalTransactionId 即可获取到完整的交易信息。那么如何从 StoreKit 1 升级到 StoreKit 2 呢?

6.6 Manager family sharing

管理家庭共享。目前苹果对 非消耗型 和 自动订阅 类型品项是支持 家庭共享(family sharing),另外,苹果会返回一个字段 inAppOwnershipType 表示当前用户是否为购买品项的主用户。更方便的追踪用户的状态

6.7 Sandbox test

小结

七、Customer Support and Handle refunds(客服支持和退款处理)

Support customers and handle refunds - WWDC21 - Videos - Apple Developer

7.1 How do I identify the in-app purchase made by this customer?

如何识别用户的购买项目。当用户扣款了,但是没有收到商品时,用户会过来返回问题并提供了苹果邮箱里的扣款信息截图。

那么我们的服务器端可以使用截图里的 invoice order ID 去请求 /inApps/v1/lookup/{customer_order_id} 这个接口查找到对应的 Transaction 信息。然后我们再去验证是否购买成功、是否已申请退款、是否需要补发商品等等。

https://developer.apple.com/documentation/appstoreserverapi/look_up_order_id
/inApps/v1/lookup/{customer_order_id}

7.2 How do I lookup this customer's past refunds?

如何查询该用户过去的退款信息?

目前的情况是,如果我们服务器宕机了或者没有收到退款通知,那么我们是不知道用户是有没有进行退款的。虽然 StoreKit 2 提供了一个获取交易记录的 API,但是如果通过该 API 来自己过滤退款的交易,不是一个最好的实现方式。所以 Apple 新提供了一个 API 可以查到这个用户的所有退款记录订单,只需要任意的一个 original_transaction_id。

https://developer.apple.com/documentation/appstoreserverapi/get_refund_history
/inApps/v1/refund/lookup/{original_transaction_id}

7.3 How do I compensate subscribers for a service issue?

如何补偿订阅者的服务问题?

比如说当服务器出问题了,为了挽留用户/吸引更多用户,计划如何给用户发补偿。开发者可以提供一个内购对兑码(所有的内购类型都可以),在苹果后台那里生成。然后让用户在 App Store 进行兑换,也可以在 App 里通过 presentCodeRedemptionSheet() 接口调用,弹出系统的兑换界面:

7.4 How do I appease customers for outages or canceled events?

如何安抚客户中断或取消的活动?

主要还是想给用户一些福利,安抚用户。类似其他 App 里的签到一个月,可以赠送用户 1 个月会员等活动。但这种方式的过期时间是由自己的服务器后端决定的。

这里 Apple 也提供了一个接口,允许开发者一年有 2 次机会给订阅内购用户每次加 90 天免费补偿。也就是有自动订阅类型的 App,可以开发者主动在服务器给用户补偿(免费延长)用户的订单时间,每次最多是 90 天。

https://developer.apple.com/documentation/appstoreserverapi/extend_a_subscription_renewal_date
/inApps/v1/subscription/extend/{original_transaction_id}

7.5 App 内如何管理订阅

同上面 5.2.4,提供了一个 showManageSubscriptions 接口,可以直接唤起管理订阅页面。

extension AppStore {
  @available(iOS 15.0, *)
  @available(macOS, unavailable)
  @available(watchOS, unavailable)
  @available(tvOS, unavailable)
  public static func showManageSubscriptions(in scene: UIWindowScene) async throws
}

7.6 APP 内 如何申请退款

同上面 5.2.5 request refund API

八、API 购买流程

原始 API 购买流程

新 API 购买流程

整个支付购买流程与原始 API 购买流程一样,区别是 3.1 步上传交易信息时,不再上传 receipt/token 信息,上传 transaction_id 就可以了。服务器端可以通过 transaction_id 去苹果服务器获取交易结果,不再需要使用 receipt/token 验证票据。

九、QA

9.1 如何选择新 API(StoreKit 2) 还是原始 API(StoreKit 1)

Choosing a StoreKit API for In-App Purchase | Apple Developer Documentation

如果您的应用程序依赖于以下任何功能,您可能需要使用原始的应用程序内购买 API:

对现有和旧应用程序使用原始 API。

老 App:

9.2 客户端使用 StoreKit 1,服务器端升级到 StoreKit 2 的 API,能否这样使用?

可以。

对于后端来说,Apple Server API V1 和 Apple Server API V2 都可以使用,与客户端是否升级到 StoreKit 2 无关。

9.3 Native SDK 使用 StoreKit 2 后,交互流程会不会有什么变化?以及与服务器通信流程会不会发生什么变化?

可以参考上面新 API 购买流程图。

9.4 StoreKit 2 会不会出现丢单的情况,以及怎么解决丢单问题?

还是有可能出现丢单的情况,例如购买成功了,Apple 返回结果时由于网络的原因导致失败了,但是此时会更容易解决。

解决办法:

9.5 购买成功但是未 finishTransaction,下次冷启动后还会重新下发 Transaction 吗?

会,与 StoreKit 1 功能一样,只是调用的接口不同。

9.6 从 StoreKit 1 升级到 StoreKit 2 后,能否看到之前使用 StoreKit 1 购买的商品?

能看到,互相兼容了。

9.7 针对使用 StoreKit1 的 app,是否可以放弃读取本地 receipt 的方式传给服务端来验证,直接采用 StoreKit2 的 transaction_id 传递给苹果服务端进行验证票据?

可以。

9.8 针对于苹果返回的 transaction 信息,我们是否能判断这个 transaction 的状态信息对应的商品类型是哪种?

可以,storekit2 针对于 transaction 的返回信息当中,明确的告诉了我们当前的商品类型是什么。针对于服务端对于消耗品和订阅商品的两套不同逻辑,我们通过这个字段,就可以轻易的区分是否是订阅商品再请求对应的接口

WWDC 视频

加载全部内容

相关教程
猜你喜欢
用户评论