メインコンテンツまでスキップ

Swift SDK 更新日志

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

5.x 版本（即将发布）​

破坏性变更​

  • 移除 PurchaseIntent —— PurchaseIntent 类型、Purchase.updates 流、PurchaseIntent.confirm() 和 PurchaseIntent.reject() 全部移除。购买结果现在直接由 product.purchase() 以 VerificationResult<Transaction> 的形式返回。

  • Product 属性重命名 —— 为与 StoreKit 2 的命名约定保持一致，Product 上的三个属性已重命名：

    旧名称新名称
    product.skuproduct.id
    product.titleproduct.displayName
    product.priceLabelproduct.displayPrice

  • Product.products() 签名变更 —— 已移除 domain: 参数：

    旧新
    Product.products(for: ["sku"], domain: "com.example.app")Product.products(for: ["sku"])

  • Purchase 类型由 Transaction 取代 —— Purchase 类型不再存在。所有交易数据现在均由 Transaction 表示。

  • purchase() 现在会抛出异常 —— Product.PurchaseResult 中已移除 .failed(let error) 情形，错误改为抛出。请将所有对 product.purchase() 的调用包裹在 do/catch 块中。

  • Purchase.unfinished() 由 Transaction.unfinished 流取代 —— 返回 [Purchase] 的函数改为不抛异常的 AsyncStream：

    旧新
    let purchases = try await Purchase.unfinished()for await result in Transaction.unfinished { }

  • transaction.finish() 不再抛出异常 —— 请将 try await purchase.finish() 替换为 await transaction.finish()。

  • transaction.id 现为 String —— 此前类型为 UInt64。请更新所有将该值作为数字存储、比较或传输的代码。

新增功能​

  • Transaction.all —— 返回应用完整交易历史的 AsyncStream<VerificationResult<Transaction>>，按时间从新到旧排列。

  • Transaction.latest(for:) —— 异步静态方法，返回指定商品标识符最近一次的 VerificationResult<Transaction>?。

  • product.latestTransaction —— Product 上的异步计算属性，返回该商品最近一次的交易。

  • product.currentEntitlement —— Product 上的异步计算属性，返回该商品当前未完成的交易（如果存在）。

迁移步骤​

  1. 将所有 Purchase 引用替换为 Transaction。 使用 Xcode 的查找与替换（Cmd+Shift+H）在整个工程中重命名该类型。

  2. 重命名 Product 属性。 将 product.sku → product.id，product.title → product.displayName，product.priceLabel → product.displayPrice。

  3. 从 Product.products() 调用中移除 domain: 参数。

  4. 将 product.purchase() 包裹在 do/catch 中并移除 .failed 情形。

    变更前：

    let result = await product.purchase()
    switch result {
    case .success(let verification): break
    case .pending: break
    case .userCancelled: break
    case .failed(let error): print("Purchase failed: \(error)")
    }

    变更后：

    do {
        let result = try await product.purchase()
        switch result {
        case .success(let verification): break
        case .pending: break
        case .userCancelled: break
        }
    } catch {
        print("Purchase failed: \(error)")
    }

  5. 将 try await purchase.finish() 改为 await transaction.finish()。

  6. 将 Purchase.unfinished() 替换为 Transaction.unfinished 流。

    变更前：

    let purchases = try await Purchase.unfinished()
    for purchase in purchases {
        giveItemToUser(productID: purchase.productID)
        try await purchase.finish()
    }

    变更后：

    for await verificationResult in Transaction.unfinished {
        switch verificationResult {
        case .verified(let transaction):
            giveItemToUser(productID: transaction.productID)
            await transaction.finish()
        case .unverified(let transaction, let error):
            print("Unverified: \(error.description)")
        }
    }

  7. 移除 Purchase.updates / PurchaseIntent 流。 改为从 product.purchase() 的返回值处理购买结果，并在启动时使用 Transaction.unfinished 进行恢复。

  8. 更新 transaction.id 的用法，在所有存储、比较或传输该值的位置将其从 UInt64 改为 String。

4.x 版本（当前版本）​

v4.3.3 —— 2026 年 7 月​

问题修复与改进

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

v4.3.2 —— 2026 年 3 月​

问题修复与改进

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

v4.3.0 —— 2026 年 3 月​

问题修复与改进

  • 移除了与 Apple MessageProtection 框架冲突的 SwiftyRSA 依赖。如果您曾为该冲突添加过临时方案，现在可以移除。
  • 为 Swift 6.2 之前的版本增加了 MarketplaceKit TransactionReporting API 的可用性检查。

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）交易上报。若要启用上报，请在应用的 Info.plist 中添加 MKSellsDigitalGoods（YES，Boolean）。

v4.0.1 —— 2025 年 12 月​

问题修复与改进

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

v4.0.0 —— 2025 年 11 月​

破坏性变更

  • Sandbox.getTestingWalletAddress() 现为 async —— 请在每个调用点添加 await：

    // Before
    let address = Sandbox.getTestingWalletAddress()

    // After
    let address = await Sandbox.getTestingWalletAddress()

  • AppcSDK.initialize() 现已强制要求 —— 如果未在每个应用入口点调用 initialize()，product.purchase() 将在运行时失败。此前这只是建议，现在是硬性要求。

新增功能

  • 以 Web Checkout 流程取代了原生结算界面。除上述破坏性变更外无需其他 API 改动——SDK 会在内部处理结算界面的呈现。
  • 增加了对较早 iOS 版本的支持。

迁移步骤

  1. 为 Sandbox.getTestingWalletAddress() 添加 await。 找出每个调用点并添加 await，必要时将外层函数标记为 async。

  2. 在每个入口点调用 AppcSDK.initialize()。 关于 SceneDelegate 和 AppDelegate 中的必要配置，请参见集成指南。

⚠️
必须在每一个应用入口点调用 AppcSDK.initialize()。关于 SceneDelegate 和 AppDelegate 中的必要配置，请参见集成指南。

3.x 版本​

v3.2.0 —— 2025 年 8 月​

问题修复与改进

  • 对于通过 TestFlight 分发的构建，AppcSDK.isAvailable() 现在返回 false。只有通过 Aptoide 分发的应用才符合 AppCoins 计费的条件。

v3.1.0 —— 2025 年 5 月​

新增功能

  • 新增可在 SDK 内访问的账户管理页面。
  • 实现了账户删除流程。

v3.0.0 —— 2025 年 5 月​

破坏性变更

  • TransactionResult 重命名为 PurchaseResult —— product.purchase() 返回的枚举已重命名。请更新所有 switch 语句和类型标注：

    // Before
    let result: TransactionResult = await product.purchase()

    // After
    let result: PurchaseResult = await product.purchase()

  • Purchase.updates 现在发出 PurchaseIntent —— 此前发出的是 VerificationResult。该流现在传递 PurchaseIntent，必须显式确认或拒绝之后购买才会完成：

    // Before
    for await verificationResult in Purchase.updates {
        if case .verified(let purchase) = verificationResult {
            giveItem(for: purchase.sku)
            try await purchase.finish()
        }
    }

    // After
    for await intent in Purchase.updates {
        let result = await intent.confirm()
        if case .success(let verificationResult) = result,
           case .verified(let purchase) = verificationResult {
            giveItem(for: purchase.sku)
            try await purchase.finish()
        }
    }

新增功能

  • 新增 PurchaseIntent.confirm() 和 PurchaseIntent.reject()，用于显式的两步式购买完成流程。

迁移步骤

  1. 使用 Xcode 的查找与替换（Cmd+Shift+H）在整个工程中将 TransactionResult 重命名为 PurchaseResult。

  2. 更新 Purchase.updates 的订阅逻辑以处理 PurchaseIntent。调用 intent.confirm() 完成购买，或调用 intent.reject() 拒绝购买。

📘
PurchaseIntent 已在 v5.x 中移除。如果您直接从 v3.x 升级到 v5.x，请完全跳过 PurchaseIntent，并按照上文的 v5.x 迁移步骤操作。

2.x 版本​

v2.1.1 —— 2025 年 3 月​

问题修复与改进

  • 修复了结算过程中关闭移动数据时不会触发开发者回调的问题。

v2.1.0 —— 2025 年 3 月​

问题修复与改进

  • 问题修复与稳定性改进。

v2.0.0 —— 2025 年 2 月​

新增功能

  • Purchase.updates —— 新增的 AsyncStream<VerificationResult>，用于传递在应用外部发起的间接应用内购买（例如来自推广链接或应用的商店页面）。请在应用启动时订阅该流，以接收并完成待处理的购买：

    Task {
        for await verificationResult in Purchase.updates {
            if case .verified(let purchase) = verificationResult {
                giveItemToUser(productID: purchase.sku)
                try await purchase.finish()
            }
        }
    }

1.x 版本​

v1.6.1 —— 2024 年 12 月​

问题修复与改进

  • 修复了在商品和购买目录较大时只返回第一页结果的分页问题。
  • 改进了认证流程的本地化与界面。

v1.6.0 —— 2024 年 11 月​

问题修复与改进

  • 使用原生 AsyncImage 替换 URLImage，修复支付方式图标消失的问题。
  • 修复了奖励金额与余额金额四舍五入不正确的问题。
  • 通过更具描述性的错误信息改进了开发者的错误调试体验。

v1.5.0 —— 2024 年 10 月​

问题修复与改进

  • 将分发格式改为 .xcframework 以提升兼容性。

v1.4.0 —— 2024 年 10 月​

问题修复与改进

  • 支付页面新增横屏方向支持。
  • 本地化改进，新增语言支持。

v1.3.0 —— 2024 年 8 月​

新增功能

  • 新增沙盒支付支持，可在不产生真实交易的情况下进行测试。
  • 商品现在以用户的本地货币显示价格。

v1.2.0 —— 2024 年 8 月​

新增功能

  • 在 Purchase 中新增验证数据，以支持服务端验证。

v1.1.0 —— 2024 年 7 月​

新增功能

  • 新增 MMP 归因支持，包含 guest_id 和 oem_id 跟踪参数。
  • Sandbox.getTestingWalletAddress() 现为同步方法。

v1.0.4 —— 2024 年 7 月​

问题修复与改进

  • 问题修复与稳定性改进。

v1.0.3 —— 2024 年 5 月​

问题修复与改进

  • 问题修复与稳定性改进。

v1.0.2 —— 2024 年 5 月​

问题修复与改进

  • 问题修复与稳定性改进。

v1.0.1 —— 2024 年 4 月​

问题修复与改进

  • 问题修复与稳定性改进。

v1.0.0 —— 2024 年 2 月​

首个版本

AppCoins iOS Swift SDK 的首个公开发布版本。

API 概览：

  • Product.products(domain:for:) —— 按 SKU 获取可用的应用内商品。
  • product.purchase(domain:payload:orderID:) —— 发起购买，返回 TransactionResult（不抛出异常；错误以 .failed 情形呈现）。
  • TransactionResult —— .success(verificationResult:)、.pending、.userCancelled、.failed(error:)。
  • VerificationResult —— .verified(purchase:)、.unverified(purchase:error:)。
  • Purchase —— 交易数据类，包含 uid、sku、state、orderUid、payload、created。
  • purchase.finish() —— 将该笔购买标记为已消耗。失败时抛出异常。
  • Purchase.unfinished() —— 返回未完成购买的 [Purchase]。会抛出异常。
  • Purchase.all() —— 返回所有购买的 [Purchase]。会抛出异常。
  • Purchase.latest(sku:) —— 返回指定 SKU 最近一次的 Purchase?。会抛出异常。
  • AppcSDK.initialize() —— 在启动时将应用注册到 SDK。
  • AppcSDK.isAvailable() —— 返回 AppCoins 计费在当前设备上是否已启用。
  • AppcSDK.handle(redirectURL:) —— 处理计费深度链接回调。