文档

Development

User Acquisition

Monetization

工业

应用内购

IAP 客户端 API

IAP SDK API

Webshop Admin API

Webshop Client API

应用内购

LiveOps
​
​
开始使用
  • 概览
  • IAP 简介
  • IAP v5 中的新功能
  • 从 IAP v4 升级到 v5
Direct to Consumer (D2C) 付款
  • 直接面向消费者(D2C)支付提供商
网上商店
  • 概览
  • 开始使用
  • 构建和发布
  • --configure
  • 连接到游戏
  • 管理员
  • 对网上商店进行故障排除
平台原生商店
  • 为平台原生商店设置 IAP
  • 无码 IAP
目录和商店管理
  • 创建商品目录
  • 支持的商店
  • 参考
购买
  • 购买管理和履行
监控 IAP 性能
  • 概览
  • IAP 收入表现
  • D2C 性能
隐私
  • 隐私与同意
  1. Unity 应用内购

从 IAP 版本 4 升级到版本 5

按照本指南从 Unity 应用内购版本 4 迁移到版本 5。
阅读时间10 分钟
最后更新于 2 个月前

应用内购 (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()
的行为:
  1. 调用并等待
    StoreController.Connect()
    :
    • 此调用完成后,IAP 将连接到您当前的应用商店。
  2. 调用:
    • 您可以将商品添加到
      CatalogProvider
      实例,类似于将商品添加到
      ConfigurationBuilder
      。您还可以将
      ProductDefinitions
      列表传递给
      ProductService.FetchProducts()
      或
      StoreController.FetchProducts()
      。有关更多信息,请参阅新初始化过程的代码示例。
    • 当请求成功完成时调用
      OnProductsFetched
      事件处理程序。如果不能获取指定商品,则会调用
      OnProductsFetchFailed
      。
  3. 成功获取商品后调用
    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
。
注意
如果在不支持的平台上获取应用商店扩展服务(例如在 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()

Copyright © 2026 Unity Technologies
法律信息隐私政策CookiesDocumentation Terms of Use请勿出售或分享我的个人信息您的隐私选择(Cookie 设置)

“Unity”、Unity 徽标及其他 Unity 商标是 Unity Technologies 或其附属公司在美国和其他地方的商标或注册商标(此处查看更多信息)。其他名称或品牌是其各自所有者的商标。

为方便起见,一些页面是机器翻译的,可能包含不准确的内容。如有信息不一致的情况,以英文版本为准。

  • 在本页上
    • 更改概述

    • 替换 UnityPurchasing.Initialize()

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

    • 替换 IDetailedStoreListener 和 IStoreListener

    • 替换 ConfigurationBuilder

    • 替换 IStoreController

    • 替换购买流程

    • 还原交易

    • 替换授权检查

    • 获取其他商品

    • 收据验证

    • Codeless IAP 特性


报告此页面的问题
​
​