从 IAP 版本 4 升级到版本 5
按照本指南从 Unity 应用内购版本 4 迁移到版本 5。
阅读时间7 分钟最后更新于 1 个月前
应用内购 (IAP) 版本 5 (v5) 引入了重大的架构改进，可更好地控制连接和购买流程的每个步骤。虽然迁移要求对现有 IAP 实现进行重大更新，但本指南提供了分步说明和代码示例来帮助您过渡。
注意
注意
从 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 工具运行 ，并提示它将项目从版本 4 迁移到版本 5。
in-app-purchases更改概述
下表总结了 IAP v5 中的更改以及在实现中需要更新的内容。有关升级的好处的更多信息，请参阅为什么应该升级到 Unity 应用内购 (IAP) v5.x 支持文章。
更改 | 所需更新 |
|---|---|
| 初始化分为商店连接、商品获取和购买获取的单独异步调用。 | 替换 UnityPurchasing.Initialize() |
| 替换 ConfigurationBuilder |
| 商店扩展将替换为商店扩展服务。 | 替换 ConfigurationBuilder |
在 | 替换 IDetailedStoreListener 和 IStoreListener |
| 替换 IStoreController |
| 更换购买流程 |
| 恢复交易 |
权利检查现在基于事件，使用 | 替换权利检查 |
Apple App Store 收据验证已弃用。Google Play 收据验证现在使用 | 更新收据验证 |
| 更新 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
- 当请求成功完成时调用
注意
默认情况下，调用 会为会话中尚未处理的任何待处理购买调用 。您可以使用 禁用此行为。
FetchPurchasesOnPurchasePendingStoreController.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 不再需要实现用于处理购买或初始化的或。通过将事件处理程序附加到 或各个 、 和 服务，替换以前由 处理的功能。
IDetailedStoreListenerIStoreListenerStoreControllerProductServicePurchaseServiceStoreServiceIDetailedStoreListener有关向 添加事件处理程序的示例，请参阅新初始化过程的代码示例。
StoreController注意
您可以随时添加或删除事件处理程序，但在调用某些方法之前，建议使用某些事件处理程序。在附加建议的事件处理程序之前调用函数时，Unity IAP 会显示警告。
要迁移，请将每个 函数替换为以下函数：
IDetailedStoreListener函数 | IAP v5 替换 |
|---|---|
| 将事件处理程序添加到 |
| 在 |
| 将事件处理程序添加到 |
| 将事件处理程序添加到 |
| 将事件处理程序添加到 |
替换 ConfigurationBuilder
将以下 函数替换为以下行为：
ConfigurationBuilder函数 | IAP v5 替换 |
|---|---|
| 您可以通过 |
| 4 和 5 | 您可以在扩展商店服务中的 |
注意
如果在不支持的平台上获取应用商店扩展服务（例如在 Editor 或 Android 上获取），则该服务将为 null。在添加事件处理程序或更改设置之前，请务必检查服务未为空。
AppleStoreExtendedService替换 IStoreController
将 替换为 。 公开了类似于 的 IAP 功能，但可以随时通过调用 来获取。
IStoreControllerStoreControllerStoreControllerIStoreListenerUnityIAPServices.StoreController()StoreController将这些来自 的方法替换为以下来自 的方法：
IStoreControllerStoreControllerIStoreController | StoreController | 注意 |
|---|---|---|
| | |
| | |
| | |
| | |
替换购买流程
要发起购买，请致电或或。要确认待定购买，请致电或，告知要确认的。有关购买流程的更多信息，请参阅购买。
Purchase()PurchaseProduct()``StoreControllerPurchaseServiceStoreController.ConfirmPurchase(PendingOrder)PurchaseService.ConfirmPurchase(PendingOrder)PendingOrder在 IAP v4 及更早版本中， 方法会自动处理所有购买事件。在 IAP v5 中，购买处理使用以下回调：
ProcessPurchase- ：为新购买调用。
OnPurchasePending - ：为恢复的购买调用。
OnPurchasesFetched
在这两个新回调中使用现有的逻辑。
ProcessPurchase还原交易
RestoreTransactionsStoreControllerPurchaseService当您调用 或通过调用 时，已确认的购买将自动恢复。
FetchPurchases()CheckEntitlement()替换授权检查
要检查用户对商品的权限，IAP 依赖于事件。您可以通过调用 并处理 事件来检查所有获取的商品的权利。要检查单个商品的权限，请调用 并处理 事件。
FetchPurchasesOnPurchasesFetchedCheckEntitlementOnCheckEntitlement获取其他商品
在 或 上调用 并提供其他商品列表以触发 事件处理程序。或者，也可以在 实例上调用 。有关通过 获取产品的示例，请参阅新初始化过程的代码示例。有关在 上调用 的示例，请参阅在 Editor 中创建目录。
StoreControllerProductServiceFetchProductsOnPurchasesFetchedCatalogProviderFetchProductsProductServiceCatalogProviderFetchProducts收据验证
Apple App Store 收据的收据验证已弃用。收据验证仅适用于 Google Play 应用商店。要获取收据，请使用 中的而不是 。
OrderOrder.Info.ReceiptProduct.Receipt注意
尽快从 StoreKit 1 收据移至 StoreKit 2 jwsRepresentation，以提高可靠性、安全性和性能，最终为用户提供更好的体验。
注意
使用 OrderInfo.Apple.jwsRepresentation 进行服务器端验证。
Codeless IAP 特性
将以下 函数替换为：
CodelessIAPStoreListener
| IAP v5 替换 |
|---|---|
| |