Unity 插件更新日志

本页记录 AppCoins iOS Unity 插件各版本的 API 变更。每个条目均列出破坏性变更、新增功能，以及适用时的迁移步骤。

---

5.x 版本（即将发布）

破坏性变更

• API 全面替换 —— 原先的直接 API（AppCoinsSDK.Instance.*）已被 Unity IAP v5 自定义商店适配器完全取代，且不提供兼容层。所有调用 AppCoinsSDK.Instance 方法的代码都必须改用 Unity IAP v5 的 StoreController 模式重写。

• 移除 AppCoinsSDK.Instance —— 以下实例方法不再存在：

  已移除的方法	替代方案
  AppCoinsSDK.Instance.IsAvailable()	AppCoinsStoreMode.Automatic（运行时自动检测）
  AppCoinsSDK.Instance.GetProducts(skus)	controller.OnProductsFetched 事件
  AppCoinsSDK.Instance.Purchase(sku, payload)	controller.InitiatePurchase(productId) + OnPurchasePending
  AppCoinsSDK.Instance.ConsumePurchase(sku)	controller.ConfirmPurchase(order)
  AppCoinsSDK.Instance.GetUnfinishedPurchases()	controller.FetchPurchases() + controller.CheckEntitlement()

• 移除 AppCoinsPurchaseManager.OnPurchaseUpdated —— 请改为订阅 controller.OnPurchasePending、controller.OnPurchaseConfirmed 和 controller.OnPurchaseFailed。

• 移除 PurchaseIntent —— ConfirmPurchaseIntent 和 RejectPurchaseIntent 不再存在。新 API 没有意图确认步骤。

• 移除 AppCoinsSDKPurchaseResult —— 由 Unity IAP v5 的订单类型取代：

  旧类型／常量	替代方案
  带 .State 字符串的 AppCoinsSDKPurchaseResult	Unity IAP 的 PendingOrder、ConfirmedOrder、FailedOrder 类型
  AppCoinsSDK.PURCHASE_STATE_SUCCESS	controller.OnPurchaseConfirmed 事件
  AppCoinsSDK.PURCHASE_STATE_FAILED	controller.OnPurchaseFailed 事件

• 移除 AppCoinsSDKResult<T> —— 结果现在通过 Unity IAP v5 的事件回调传递。

• 现在必须使用 Unity IAP v5 —— 必须将 com.unity.purchasing 5.0 或更高版本添加为包依赖。

• 要求 Unity 2022.3 或更高版本 —— 支持的最低 Unity 版本已从 2019.4 提升至 2022.3。

新增功能

• AppCoinsIAP.ConfigureStoreAsync(AppCoinsStoreMode) —— 插件配置的唯一入口点，必须在 StoreController.Connect() 之前调用。返回所选商店的名称（"AppCoinsAppStore" 或 "AppleAppStore"）。

• AppCoinsStoreMode.Automatic —— 执行运行时检查，并根据 iOS 版本和安装来源选择 AppCoins 或 Apple 计费。参见运行时检测的原理。

• 完整的 Unity IAP v5 兼容性 —— 无论当前使用哪个商店，所有标准 Unity IAP v5 事件（OnProductsFetched、OnPurchasePending、OnPurchaseConfirmed、OnPurchaseFailed）的行为完全一致。

• 内置带验证数据的收据 —— order.Info.Receipt 包含一段 JSON 负载，其中含有用于服务端验证的 Payload.verification.data.purchaseToken。

迁移步骤

1. 从 Assets 中移除旧插件。 删除 AppCoinsSDK.cs、AppCoinsPurchaseManager.cs、AppCoinsSDKPurchaseResult.cs、AppCoinsSDKResult.cs 及所有相关文件。

2. 从 GitHub releases 添加新插件。 下载最新的 .unitypackage 并将其导入 Assets 文件夹。

3. 通过 Package Manager 添加 com.unity.purchasing 5.0 或更高版本。 打开 Window → Package Manager，搜索 In App Purchasing 并安装 5.0 或更高版本。

4. 将所有 AppCoinsSDK.Instance.* 调用替换为 Unity IAP v5 的 StoreController 模式：

   • IsAvailable() → AppCoinsIAP.ConfigureStoreAsync(AppCoinsStoreMode.Automatic)
   • GetProducts(skus) → 订阅 controller.OnProductsFetched
   • Instance.Purchase(sku, payload) → controller.InitiatePurchase(productId)
   • 在 controller.OnPurchasePending 中处理购买结果

5. 将 ConsumePurchase(sku) 替换为 controller.ConfirmPurchase(order)。 新方法接收来自 OnPurchasePending 的 PendingOrder 对象，而不是 SKU 字符串。

6. 在 controller.Connect() 之前添加一次 ConfigureStoreAsync 调用：

   await AppCoinsIAP.ConfigureStoreAsync(AppCoinsStoreMode.Automatic);
   await _controller.Connect();

完整的变更前后示例请参见迁移指南全文：从旧版 AppCoins Unity 插件升级

---

4.x 版本（当前版本）

v4.3.3 —— 2026 年 7 月

问题修复与改进

• 通过指数退避重试逻辑提升了归因的可靠性。
• 提高了日志级别，确保 SDK 生命周期日志能够在设备上持久保存。

v4.3.2 —— 2026 年 3 月

问题修复与改进

• 修复了访客账户转换为用户账户后 getWalletList 返回重复钱包的问题。

v4.3.1 —— 2026 年 3 月

问题修复与改进

• 修复了 PURCHASE_STATE_USER_CANCELLED 常量值与 AppCoins SDK 返回值不一致的问题。

v4.3.0 —— 2026 年 3 月

问题修复与改进

• 为插件类添加了 AppCoins 命名空间，以避免与其他包发生命名冲突。
• 修复了 SDK 同时链接到主 target 和 UnityFramework、导致 Xcode 出现重复类警告的问题。
• 移除了与 Apple MessageProtection 框架冲突的 SwiftyRSA 依赖。如果您曾为该冲突添加过临时方案，现在可以移除。

v4.2.0 —— 2026 年 2 月

问题修复与改进

• 在 Web Checkout URL 中新增 installation_origin 和 oem_id 参数，以改善归因效果。

v4.1.2 —— 2026 年 2 月

问题修复与改进

• 修复了无论安装来源如何都会触发 MMP 安装事件的问题。该事件现在仅在通过 Aptoide 分发安装时触发。

v4.1.1 —— 2026 年 2 月

新增功能

• 新增 CTC（Catappult Token Contribution）交易上报。Xcode 后处理构建脚本现在会自动将 Info.plist 中的 MKSellsDigitalGoods 设置为 YES，无需手动配置。

v4.0.1 —— 2025 年 12 月

问题修复与改进

• AppCoinsSDK.Instance.IsAvailable() 恢复为默认返回 false。此前修改该默认值的变更已被回退。
• 为兼容 Swift 6.2，提升了 web3swift 包依赖的版本。

v4.0.0 —— 2025 年 11 月

破坏性变更

• AppCoinsSDK.Instance.IsAvailable() 现在要求先调用 Initialize() —— 如果尚未调用 Initialize()，该方法将直接返回 false，而不会执行实时可用性检查。未先调用 Initialize() 就调用 IsAvailable() 的代码将始终得到 false。

新增功能

• 以 Web Checkout 流程取代了原生结算界面，无需任何 API 改动。
• 若未调用 Initialize()，AppCoinsSDK.Instance.IsAvailable() 现在会返回 false。请确保在任何购买尝试之前调用 Initialize()。
• 增加了对较早 iOS 版本的支持。

迁移步骤

1. 确保在每个应用入口点都先调用 Initialize() 再调用 IsAvailable()。 请将 Initialize() 调用移至 Awake() 或初始化流程中最早的 Start()。

---

3.x 版本

v3.0.0 —— 2025 年 5 月

破坏性变更

• AppCoinsPurchaseManager.OnPurchaseUpdated 的回调类型变更 —— 事件签名已从 Action<PurchaseResponse> 改为 Action<PurchaseIntent>。所有现有处理方法都必须改写为接收新类型，并在访问购买数据之前调用 ConfirmPurchaseIntent() 或 RejectPurchaseIntent()：

  // Before (v2.x)
  private void OnPurchaseUpdated(PurchaseResponse response)
  {
      if (response.State == AppCoinsSDK.PURCHASE_STATE_SUCCESS)
      {
          GiveItemToUser(response.Purchase.Sku);
          StartCoroutine(ConsumePurchase(response.Purchase.Sku));
      }
  }
  
  // After (v3.0.0)
  private void OnPurchaseUpdated(PurchaseIntent intent)
  {
      var result = AppCoinsSDK.Instance.ConfirmPurchaseIntent(intent);
      if (result.IsSuccess)
          GiveItemToUser(intent.Purchase.Sku);
      else
          AppCoinsSDK.Instance.RejectPurchaseIntent(intent);
  }

• 错误现在是结构化对象 —— AppCoinsSDKError 取代了原始错误字符串。此前将 .Error 与字符串常量比较的代码必须改为使用新的类型化错误类。

新增功能

• 引入 AppCoinsSDKError 以提供结构化的错误上报。SDK 调用返回的错误现在包含类型化错误类，便于识别。
• 将响应类型重构为 AppCoinsSDKResult<T>，使所有异步操作的处理方式保持一致。
• 新增对延迟间接购买的支持，并可通过 RejectPurchaseIntent() 拒绝某个 PurchaseIntent。

迁移步骤

1. 更新所有 OnPurchaseUpdated 处理方法，使其接收 PurchaseIntent 而非 PurchaseResponse。将对 response.State 和 response.Purchase 的访问替换为调用 AppCoinsSDK.Instance.ConfirmPurchaseIntent(intent) 以完成购买，或调用 RejectPurchaseIntent(intent) 以拒绝购买。

2. 更新错误处理，改用 AppCoinsSDKError 而非原始字符串比较。可通过 AppCoinsSDKResult<T>.Error 访问错误，该对象现在暴露 Type、Message 和 Description 字段。

---

2.x 版本

v2.0.1 —— 2025 年 3 月

问题修复与改进

• 修复了在 SDK 不可用时短时间内多次调用 Purchase() 导致崩溃的问题。

v2.0.0 —— 2025 年 3 月

新增功能

• 为 Purchase.updates 新增监听器，用于处理间接应用内购买（在应用外部发起的购买）。
• 将 AppCoins SDK 的最低依赖版本设为 v2.0.0，新增对用户认证和开发者测试功能的支持。

---

1.x 版本

1.x 版本提供的是一套直接的单例 API（AppCoinsSDK.Instance），为每项计费操作提供异步方法，所有结果均以 AppCoinsSDKResult<T> 包装形式返回。

主要 API 概览（供参考）：

• AppCoinsSDK.Instance.IsAvailable() → AppCoinsSDKResult<Bool>
• AppCoinsSDK.Instance.GetProducts(skus) → AppCoinsSDKResult<[AppCoinsProduct]>
• AppCoinsSDK.Instance.Purchase(sku, payload) → 通过 AppCoinsPurchaseManager.OnPurchaseUpdated 传递
• AppCoinsSDK.Instance.ConsumePurchase(sku) → AppCoinsSDKResult<Void>
• AppCoinsSDK.Instance.GetUnfinishedPurchases() → AppCoinsSDKResult<[AppCoinsPurchase]>

以上内容均已在 v5.x 中移除。请按照 5.x 版本下列出的迁移步骤更新您的工程。