iOS StoreKit 2 新特性解析

一、背景

2021 年 WWDC，在 iOS 15 系統上推出了一個新的 StoreKit 2 庫，該庫采用了完全新的 API 來解決應用內購買問題。

Meet StoreKit 2 - WWDC21 - Videos - Apple Developer：重點內容：Storekit 2 API 介紹和代碼演示,以及 appAccountToken
Manage in-app purchases on your server - WWDC21 - Videos - Apple Developer：重點內容：JWS 簽名交易的服務器驗證，新服務器 API，新服務器通知，沙盒測試的新功能
Support customers and handle refunds - WWDC21 - Videos - Apple Developer：重點內容：用來支持用戶和處理退款的 Storekit 2 API 以及服務器 API

二、物料

名詞	解釋
IAP	In-App Purchase：應用內購買
StoreKit 1	原始的應用內購買 API	Choosing a StoreKit API for In-App Purchase
StoreKit 2	應用內購買 API	Choosing a StoreKit API for In-App Purchase

三、StoreKit 1 存在的問題

1 . 蘋果后臺能否查看到退款的訂單詳情？

不能。只能蘋果處理退款后發通知給我們的服務器，告知發生了一筆退款

2 . 消耗性、非消耗性、非續期訂閱、自動續訂能不能在沙盒環境測試退款？

不能。系統沒提供這種測試方式。

3 . 能夠將用戶反饋的蘋果收據里的 orderID 與具體的交易進行關聯嗎？

不能。

服務器端 Receipt 收據解析后，沒有包含 orderID 信息，所以無法直接關聯他們之間的聯系。
不支持使用蘋果收據里的 orderID 去蘋果服務器查詢交易信息，沒有提供這個 API（StoreKit 2 出來后支持去查詢 StoreKit1 的交易了，https://developer.apple.com/documentation/appstoreserverapi/look_up_order_id?language=_9 ）。

4 . 在開發過程中，無法直接關聯 transaction 與 orderID 之間聯系，雖然有一個 applicationUserName 字段，可以存儲一個信息。但是這個字段是不是 100%靠譜，在某些情況下會丟失存儲的數據。

5 . 無法主動的去蘋果服務器獲取交易歷史記錄，退款信息。無法根據用戶提供的蘋果收據里的 orderID 主動關聯上我們當前已知的訂單。

6 . 目前 sk1 的 skproduct 無法區分消耗品，非消耗品，訂閱商品，非連續訂閱商品。

7 . sk1 存在隊列監聽，每次購買需要通過隊列監聽對應的購買狀態的變更，所有的 transaction 的回調都在監聽當中，不好區分哪些是補單的 transaction 和正常購買的 transaction。

四、StoreKit v2 新特性

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

StoreKit 2：關于在 App 里 API 的更新和變化，包含應用內更改訂閱、退款等；
Server to Server：蘋果服務器與開發者服務器之間的通訊，包括蘋果通知、開發者主動請求蘋果服務器、新的驗證收據流程等；
Sandbox Test：關于沙盒測試環境相關的更新，還有一些注意事件等。

五、StoreKit 2 API

StoreKit 2 主要的更新有這幾個：

使用 swift 新特性開發
更新收據和交易（數據格式和字段變更）
更多訂閱類型的接口
相同的 StoreKit 框架

5.1 只支持 Swift 開發

StoreKit 2 使用了 Swift 5.5 的新特性進行開發，完全修改了獲取商品、發起交易、管理交易信息等接口 API 的實現方式。https://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

新增了一些商品類型，訂閱信息，這些字段信息在 StoreKit 1 里是沒有的。

方便我們利用的字段：

通過新增的 product type 我們可以輕易的知道當前的商品是消耗品還是訂閱商品
針對于自動連續訂閱的第一次購買優惠，我們可以直接感知到當前的商品是不是用戶的 Apple ID 下的第一次購買

舉個例子：

某些 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

提供了新的購買商品接口。其中購買商品時增加了一些可選參數 PurchaseOption 結構體，該結構體里有新增的特別重要的字段appAccountToken，類似 SKPayment.applicationUsername 字段，但是 appAccountToken 信息會永久保存在 Transaction 信息內。

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
    }
  }

處理驗證 Transaction。系統會驗證是否是一個合法的 Transaction，此時系統不再提供 base64 的 receip string 信息，只需要上傳 transaction.id 和 transaction.originalID，服務器端根據需要選擇合適的 ID 進行驗證。

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
    }
  }

監聽 Transaction 更新

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 的更新，這個監聽是讓我們監聽：

這筆訂單用戶開啟了一筆購買，這筆訂單在蘋果那邊還沒有得到結果，用戶殺死 app 或者用戶卸載了 app 并重新安裝 app，這個時候我們可以通過這個監聽收到對應的 transaction 更新
用戶發起一筆購買，這筆購買可能因為網絡狀態不好的因素，在端上收到了失敗的 transaction 回調，但是后續蘋果發現這種 case，重新下發 transaction 到端上進行對應的驗證。

5.2.2 Transaction History

提供了三個新的交易（Transcation）相關的 API：

All transactions：全部的購買交易訂單，在 transaction 里面獲取
Latest transactions：最新的購買交易訂單。
Current entitlements：所有當前訂閱的交易，以及所有購買（且未退還）的非消耗品。

根據可以購買的訂閱商品、非消耗品可以過濾出已經購買過的商品。

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 }
}

同步不同設備的購買記錄。這個 API 可以替換 StoreKit 1 里面的恢復購買 API，調用該方法后，系統會彈出提示框要求輸入 AppleID 帳號密碼信息。

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
}

5.2.6 總結：

StoreKit 2 庫采用 Swift 5.5 版本最新特性重寫，只支持 Swift、iOS 15+，提供了一些新的 API 接口，導致新的支付流程會發生一些變化。
提供了獲取交易歷史記錄、可購買的商品列表(自動續期訂閱以及非消耗品)信息
提供了獲取訂閱狀態、管理訂閱狀態接口
支持在 App 內發起退款

六、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

獲取訂閱狀態：get_all_subscription_statuses，只需要一個 originalTransactionId 參數，就可以獲取用戶訂閱的各種狀態
獲取交易歷史記錄：get_transaction_history，只需要用戶任意一個交易里的 originalTransactionId 即可獲取所有的歷史記錄
在您的服務器收到消費請求通知后，將有關應用程序內消費品購買的消費信息發送到應用程序商店。（主要用于用戶申請退款后，告知 App Store 購買的商品有沒有被消費，用于評估是否需要退款）。send_consumption_information
App Store Server API standards：JSON Web Signature (JWS)

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 呢？

上傳 receipt 到我們的服務器
拿著 receipt 去蘋果服務器驗證，并獲取 originalTransactionId 信息
根據 originalTransactionId 去蘋果服務器獲取歷史交易記錄，找到特定 originalTransactionId，Transaction
如果是訂閱類型的商品，可以繼續去獲取訂閱狀態

6.6 Manager family sharing

管理家庭共享。目前蘋果對非消耗型和自動訂閱類型品項是支持家庭共享（family sharing），另外，蘋果會返回一個字段 inAppOwnershipType 表示當前用戶是否為購買品項的主用戶。更方便的追蹤用戶的狀態

6.7 Sandbox test

清楚沙盒賬號購買記錄
新增沙盒環境的回調 URL 配置
改變沙盒賬號國家/地區
調整沙盒續訂頻率
安全性改良：testFlight 版本驗證票據將失敗

6.8 總結

以前只支持 Apple server 單向發送狀態變化的通知給我們自己的服務器，現在支持主動去請求 Apple server 獲取歷史交易記錄，訂閱狀態信息
StoreKit 2 服務器端接口支持了新的格式(JWS 格式)。
沙盒環境測試優化

七、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 購買流程

請求 Product
發起購買
接收回調，成功后上傳 receipt
服務器驗證 receipt 并發貨

新 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：

為批量采購計劃（VPP）提供支持。有關更多信息，請參閱設備管理。
提供應用程序預購。有關更多信息，請參閱為預購提供應用程序。
您的應用程序從高級版更改為免費版，反之亦然。

對現有和舊應用程序使用原始 API。

如果是一個全新的 App，只支持 iOS 15+系統且支持 Swift5 開發成本不大，推薦使用 StoreKit 2，但是使用 StoreKit 1 也沒有問題；

老 App：

從 SDK 角度來看，可以單獨新增一個子倉支持 StoreKit 2。即使目前不支持，以后遲早也會支持。
從宿主角度來看，要不要激進的引入新功能。引入新功能后會不會帶來 OC 與 Swift 混編的問題，以及引入新功能后需要做好相應的 backup 方案。

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 返回結果時由于網絡的原因導致失敗了，但是此時會更容易解決。

解決辦法：

冷啟動時，可監聽 Transaction 變化，收到成功的 Transaction 后重新上傳，與 StoreKit 1 類似。
在購買時向 product 內 appAccountToken 字段里塞入業務方 orderID 相關的信息，當用戶反饋扣款了但是沒發貨時，可以讓用戶提供 Apple 的 orderID，通過它可以直接去蘋果服務器獲取對應的 Transaction 信息，找到 Transaction.appAccountToken ，再給用戶發貨。（這里可以做成一個自動化處理工具，只需要用戶提供蘋果的 orderID，就可以去查找對應的業務方 orderID 進行發貨。）

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 視頻

Meet StoreKit 2 - WWDC21 - Videos - Apple Developer：重點內容：Storekit 2 API 介紹和代碼演示,以及 appAccountToken
Manage in-app purchases on your server - WWDC21 - Videos - Apple Developer：重點內容：JWS 簽名交易的服務器驗證，新服務器 API，新服務器通知，沙盒測試的新功能
Support customers and handle refunds - WWDC21 - Videos - Apple Developer：重點內容：用來支持用戶和處理退款的 Storekit 2 API 以及服務器 API
What’s new with in-app purchase - WWDC20 - Videos - Apple Developer：重點內容：退款通知，家人共享和 SKAdNetwork
In-App Purchases and Using Server-to-Server Notifications - WWDC19 - Videos - Apple Developer：重點內容：App Store 服務器通知詳解
What's New in StoreKit - WWDC17 - Videos - Apple Developer：重點內容：標準 IAP 支付流程，applicationUserName，promoted IAP

其他資料

自動續期訂閱
App Store Server API | Apple Developer Documentation
【WWDC21 10114】初見 StoreKit 2 - 小專欄

https://mp.weixin.qq.com/s/RrkK5M3qYTs2cMi7sWTqrA

一、背景

二、物料

三、StoreKit 1 存在的問題

四、StoreKit v2 新特性

五、StoreKit 2 API