从 IAP 版本 4 升级到版本 5

按照本指南从 Unity 应用内购版本 4 迁移到版本 5。

阅读时间7 分钟

最后更新于 20 天前

应用内购 (IAP) 版本 5 (v5) 引入了重大的架构改进，可更好地控制连接和购买流程的每个步骤。虽然迁移要求对现有 IAP 实现进行重大更新，但本指南提供了分步说明和代码示例来帮助您过渡。

注意

从 SDK v5.4 开始，Unity IAP 将开发者数据处理为开发者数据框架的一部分。因此，您有责任使用 UnityConsent 模块管理用户同意。

注意

从 IAP 5.3.0 版本开始，您可以访问 IAP AI 技能来帮助将项目从版本 4 迁移到版本 5。在 Project Settings > Services > In-App Purchasing 的底部，选择以下选项之一：

打开技能文件夹：打开包含技能文件的文件夹。使用此选项可在首选 AI 工具中复制或安装 IAP AI 技能。
安装到 Claude Code：将技能直接添加到 Claude Code。这将安装一个名为
```
in-app-purchases
```
的技能。

安装该技能后，请从 AI 工具运行

in-app-purchases

，并提示它将项目从版本 4 迁移到版本 5。

更改概述

下表总结了 IAP v5 中的更改以及在实现中需要更新的内容。有关升级的好处的更多信息，请参阅为什么应该升级到 Unity 应用内购 (IAP) v5.x 支持文章。

更改	所需更新
初始化分为商店连接、商品获取和购买获取的单独异步调用。	替换 UnityPurchasing.Initialize()
`ConfigurationBuilder` 被删除。产品现在通过 `CatalogProvider` 或 `ProductDefinitions` 列表进行定义。	替换 ConfigurationBuilder
商店扩展将替换为商店扩展服务。	替换 ConfigurationBuilder
在 `StoreController` 和各个商店服务上， `IDetailedStoreListener` 和 `IStoreListener` 替换为可选的事件处理程序。	替换 IDetailedStoreListener 和 IStoreListener
`IStoreController` 替换为 `StoreController` ，可随时通过 `UnityIAPServices.StoreController()` 获取。	替换 IStoreController
`ProcessPurchase` 回调替换为新购买的 `OnPurchasePending` 和恢复购买的 `OnPurchasesFetched` 。	更换购买流程
`RestoreTransactions` 已从 Store Extensions 移至 `StoreController` 和 `PurchaseService` 。	恢复交易
权利检查现在基于事件，使用 `FetchPurchases` 或 `CheckEntitlement` 。	替换权利检查
Apple App Store 收据验证已弃用。Google Play 收据验证现在使用 `Order.Info.Receipt` 。	更新收据验证
`CodelessIAPStoreListener.initializationComplete` 替换为 `CodelessIAPStoreListener.IsInitialized()` 。	更新 Codeless IAP

替换 UnityPurchasing.Initialize()

从 IAP v5 开始，您可以更灵活地初始化 Unity IAP 包。您可以独立和异步连接到商店、获取商品和处理购买。此方法可以帮助您识别和解决可能阻止成功初始化的问题。

注意

在版本 4 和更早版本中，Unity IAP 包连接到商店，获取商品，并在包初始化时同步获取购买。只有在完成所有这些步骤后，包才会报告初始化成功。

按照以下步骤替换

UnityPurchasing.Initialize()

的行为：

调用并等待
```
StoreController.Connect()
```
：
- 此调用完成后，IAP 将连接到您当前的应用商店。
调用：
- 您可以将商品添加到
```
CatalogProvider
```
  实例，类似于将商品添加到
```
ConfigurationBuilder
```
  。您还可以将
```
ProductDefinitions
```
  列表传递给
```
ProductService.FetchProducts()
```
  或
```
StoreController.FetchProducts()
```
  。有关更多信息，请参阅新初始化过程的代码示例。
- 当请求成功完成时调用
```
OnProductsFetched
```
  事件处理程序。如果不能获取指定商品，则会调用
```
OnProductsFetchFailed
```
  。
成功获取商品后调用
```
FetchPurchases()
```
：
- 当请求成功完成时调用
```
OnPurchasesFetched
```
  事件处理程序。
```
Orders
```
  对象包含应用商店返回的所有延迟、待处理和已完成订单的可过滤集合。失败时会调用
```
OnPurchasesFetchFailed
```
  。

注意

默认情况下，调用

FetchPurchases

会为会话中尚未处理的任何待处理购买调用

OnPurchasePending

。您可以使用

StoreController.ProcessPendingOrdersOnPurchasesFetched(false)

禁用此行为。

使用 StoreController 的新初始化过程的代码示例

以下示例展示了如何初始化 IAP v5：


StoreController m_StoreController;    async void InitializeIAP()  {      m_StoreController = UnityIAPServices.StoreController();        m_StoreController.OnPurchasePending += OnPurchasePending;        await m_StoreController.Connect();        m_StoreController.OnProductsFetch += OnProductsFetch;    m_StoreController.OnPurchasesFetch += OnPurchasesFetch;        var initialProductsToFetch = new List<ProductDefinition>      {          new(goldProductId, ProductType.Consumable),         new(diamondProductId, ProductType.Consumable)      };        m_StoreController.FetchProducts(initialProductsToFetch);  }void OnProductsFetched(List<Product> products)  {      // Handle fetched products      m_StoreController.FetchPurchases();  }  void OnPurchasesFetched(Orders orders) {     // Process purchases, for example, check for entitlements from completed orders  }

替换 IDetailedStoreListener 和 IStoreListener

IAP v5 不再需要实现用于处理购买或初始化的

IDetailedStoreListener

或

IStoreListener

。通过将事件处理程序附加到

StoreController

或各个

ProductService

、

PurchaseService

和

StoreService

服务，替换以前由

IDetailedStoreListener

处理的功能。有关向

StoreController

添加事件处理程序的示例，请参阅新初始化过程的代码示例。

注意

您可以随时添加或删除事件处理程序，但在调用某些方法之前，建议使用某些事件处理程序。在附加建议的事件处理程序之前调用函数时，Unity IAP 会显示警告。

要迁移，请将每个

IDetailedStoreListener

函数替换为以下函数：

函数	IAP v5 替换
`OnPurchaseFailed(Product, PurchaseFailureDescription)`	将事件处理程序添加到 `StoreController.OnPurchaseFailed(FailedOrder)` 或 `PurchaseService.OnPurchaseFailed(FailedOrder)`
`OnInitialized(IStoreController controller, IExtensionProvider extensions)`	在 `StoreController.Connect()` 或 `StoreService.Connect()` 完成后继续执行。
`OnInitializeFailed(InitializationFailureReason error)`	将事件处理程序添加到 `StoreService.OnStoreDisconnected(StoreConnectionFailureDescription)` 、 `ProductService.OnProductsFetchFailed(ProductFetchFailed)` 和 `PurchaseService.OnPurchasesFetchFailed(PurchasesFetchFailureDescription)` 。还可以通过 `StoreController` 添加这些事件处理程序。
`OnInitializeFailed(InitializationFailureReason error, string message = null)`	将事件处理程序添加到 `StoreController.OnStoreDisconnected(StoreConnectionFailureDescription)` 或 `StoreService.OnStoreDisconnected(StoreConnectionFailureDescription)`
`PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs args)`	将事件处理程序添加到 `StoreController.OnPurchasePending(PendingOrder)` 或 `PurchaseService.OnPurchasePending(PendingOrder)`

替换 ConfigurationBuilder

将以下

ConfigurationBuilder

函数替换为以下行为：

函数	IAP v5 替换
`ConfigurationBuilder.AddProduct()`	您可以通过 `CatalogProvider.AddProduct()` 或 `CatalogProvider.AddProducts()` 将商品添加到 `CatalogProvider` 实例，而不是调用 `ConfigurationBuilder.AddProduct()` 。要获取商品，可以调用 `CatalogProvider.FetchProducts` 并传递回调（例如 `UnityIAPServices.DefaultProduct().FetchProductsWithNoRetries` ）。有关产品和 `CatalogProvider` 的更多信息，请参阅在 Editor 中创建目录。还可以创建 `ProductDefinitions` 并将其直接传递给 `StoreController` 或 `ProductService` 上的 `FetchProducts()` 调用。
4 和 5	您可以在扩展商店服务中的 `IAppleConfiguration` 和 `IGoogleConfiguration` 中找到功能，例如 `AppleStoreExtendedService` 。

函数

IAP v5 替换

ConfigurationBuilder.AddProduct()

您可以通过

CatalogProvider.AddProduct()

或

CatalogProvider.AddProducts()

将商品添加到

CatalogProvider

实例，而不是调用

ConfigurationBuilder.AddProduct()

。要获取商品，可以调用

CatalogProvider.FetchProducts

并传递回调（例如

UnityIAPServices.DefaultProduct().FetchProductsWithNoRetries

）。有关产品和

CatalogProvider

的更多信息，请参阅在 Editor 中创建目录。还可以创建

ProductDefinitions

并将其直接传递给

StoreController

或

ProductService

上的

FetchProducts()

调用。

4 和 5

您可以在扩展商店服务中的

IAppleConfiguration

和

IGoogleConfiguration

中找到功能，例如

AppleStoreExtendedService

。

注意

如果在不支持的平台上获取应用商店扩展服务（例如在 Editor 或 Android 上获取

AppleStoreExtendedService

），则该服务将为 null。在添加事件处理程序或更改设置之前，请务必检查服务未为空。

替换 IStoreController

将

IStoreController

替换为

StoreController

。

StoreController

公开了类似于

IStoreListener

的 IAP 功能，但可以随时通过调用

UnityIAPServices.StoreController()

来获取

StoreController

。将这些来自

IStoreController

的方法替换为以下来自

StoreController

的方法：

IStoreController	StoreController	注意
`products`	`GetProducts`	`GetProducts` 返回商品列表。
`InitiatePurchase`	`Purchase` 或 `PurchaseProduct`	`Purchase` 函数不再具有 `payload` 参数。在 Google Billing v3 中移除了对开发者有效负载的支持。
`FetchAdditionalProducts`	`FetchProducts`	`FetchProducts` 还用于获取初始商品。
`ConfirmPendingPurchase`	`ConfirmPurchase`	`ConfirmPurchase` 需要 `PendingOrder` 。

替换购买流程

要发起购买，请致电

Purchase()

或

PurchaseProduct()``StoreController

或

PurchaseService

。要确认待定购买，请致电

StoreController.ConfirmPurchase(PendingOrder)

或

PurchaseService.ConfirmPurchase(PendingOrder)

，告知要确认的

PendingOrder

。有关购买流程的更多信息，请参阅购买。在 IAP v4 及更早版本中，

ProcessPurchase

方法会自动处理所有购买事件。在 IAP v5 中，购买处理使用以下回调：

```
OnPurchasePending
```
：为新购买调用。
```
OnPurchasesFetched
```
：为恢复的购买调用。

在这两个新回调中使用现有的

ProcessPurchase

逻辑。

还原交易

RestoreTransactions

已从 Store Extensions 移至

StoreController

和

PurchaseService

。当您调用

FetchPurchases()

或通过调用

CheckEntitlement()

时，已确认的购买将自动恢复。

替换授权检查

要检查用户对商品的权限，IAP 依赖于事件。您可以通过调用

FetchPurchases

并处理

OnPurchasesFetched

事件来检查所有获取的商品的权利。要检查单个商品的权限，请调用

CheckEntitlement

并处理

OnCheckEntitlement

事件。

获取其他商品

在

StoreController

或

ProductService

上调用

FetchProducts

并提供其他商品列表以触发

OnPurchasesFetched

事件处理程序。或者，也可以在

CatalogProvider

实例上调用

FetchProducts

。有关通过

ProductService

获取产品的示例，请参阅新初始化过程的代码示例。有关在

CatalogProvider

上调用

FetchProducts

的示例，请参阅在 Editor 中创建目录。

收据验证

Apple App Store 收据的收据验证已弃用。收据验证仅适用于 Google Play 应用商店。要获取收据，请使用

Order

中的

Order.Info.Receipt

而不是

Product.Receipt

。

注意

尽快从 StoreKit 1 收据移至 StoreKit 2 jwsRepresentation，以提高可靠性、安全性和性能，最终为用户提供更好的体验。

注意

使用 OrderInfo.Apple.jwsRepresentation 进行服务器端验证。

Codeless IAP 特性

将以下

CodelessIAPStoreListener

函数替换为：

`函数` CodelessIAPStoreListener`	IAP v5 替换
`CodelessIAPStoreListener.initializationComplete`	`CodelessIAPStoreListener.IsInitialized()`

文档

Development

User Acquisition

Monetization

工业

文档

Development

User Acquisition

Monetization

工业

应用内购

IAP 客户端 API

IAP SDK API

Webshop Admin API

Webshop Client API

应用内购

从 IAP 版本 4 升级到版本 5

更改概述

更改

所需更新

替换 UnityPurchasing.Initialize()

使用 StoreController 的新初始化过程的代码示例

替换 IDetailedStoreListener 和 IStoreListener

函数

IAP v5 替换

替换 ConfigurationBuilder

函数

IAP v5 替换

替换 IStoreController

IStoreController

StoreController

注意

替换购买流程

还原交易

替换授权检查

获取其他商品

收据验证

Codeless IAP 特性

`函数`
CodelessIAPStoreListener`

IAP v5 替换

从 IAP 版本 4 升级到版本 5

更改概述

更改

所需更新

替换 UnityPurchasing.Initialize()

使用 StoreController 的新初始化过程的代码示例

替换 IDetailedStoreListener 和 IStoreListener

函数

IAP v5 替换

替换 ConfigurationBuilder

函数

IAP v5 替换

替换 IStoreController

IStoreController

StoreController

注意

替换购买流程

还原交易

替换授权检查

获取其他商品

收据验证

Codeless IAP 特性

函数CodelessIAPStoreListener`

IAP v5 替换

`函数`
CodelessIAPStoreListener`