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

二、物料

三、StoreKit 1 存在的問題

• 蘋果後臺能否檢視到退款的訂單詳情？

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

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

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

• 能夠將使用者反饋的蘋果收據裡的 orderID 與具體的交易進行關聯嗎？

不能。

• 伺服器端 Receipt 收據解析後，沒有包含 orderID 資訊，所以無法直接關聯他們之間的聯絡。

不支援使用蘋果收據裡的 orderID 去蘋果伺服器查詢交易資訊，沒有提供這個 API（StoreKit 2 出來後支援去查詢 StoreKit1 的交易了，developer.apple.com/documentati… ）。

• 在開發過程中，無法直接關聯 transaction 與 orderID 之間聯絡，雖然有一個 applicationUserName 欄位，可以儲存一個資訊。但是這個欄位是不是 100%靠譜，在某些情況下會丟失儲存的資料。
• 無法主動的去蘋果伺服器獲取交易歷史記錄，退款資訊。無法根據使用者提供的蘋果收據裡的 orderID 主動關聯上我們當前已知的訂單。
• 目前 sk1 的 skproduct 無法區分消耗品，非消耗品，訂閱商品，非連續訂閱商品。
• 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 的實現方式。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
}

小結：

• 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 版本驗證票據將失敗

小結

• 以前只支援 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

以上就是iOS StoreKit 2 新特性盤點解析的詳細內容，更多關於iOS StoreKit 2 新特性的資料請關注it145.com其它相關文章！