更新记录

1.0.0（2026-06-05）

支持 三端内购

平台兼容性

uni-app(5.08)

uni-app x(5.08)

tt-iap-sdk

tt-iap-sdk 是面向 uni-app / uni-app x 的三端应用内购客户端插件，统一封装：

• Android：Google Play Billing
• iOS：StoreKit2
• HarmonyOS：IAP Kit

插件只负责客户端侧的环境诊断、商品查询、拉起购买、查询待处理订单、恢复已购和完成交易。不包含服务端验单、发货、订阅权益管理、退款处理和风控逻辑。

平台支持

集成前准备

三端内购不是只接入客户端插件就能上线。集成前请先完成以下准备。

通用准备

1. 确认商品类型和商品 ID。
   • 消耗型：金币、次数、道具等，可重复购买，发货后调用 consume。
   • 非消耗型：永久解锁、去广告等，购买后调用 finish。
   • 订阅：会员、周期服务等，购买后调用 finish。
2. 在对应平台后台创建商品，确保 App 包名/Bundle ID、商品 ID、商品类型完全匹配。
3. 准备测试账号和沙盒/测试渠道。
4. 准备业务订单号、用户标识和发货逻辑。
5. 准备服务端验单和幂等发货逻辑。客户端返回的 receipt、purchaseToken、signature 等只能作为验单材料，不应直接作为最终发货依据。
6. 设计补单流程：App 启动、进入支付页、用户反馈未到账时调用 getPendingPurchases 或 restore。

Android / Google Play 准备

1. 在 Google Play Console 创建应用，包名必须和 Android 应用一致。
2. 创建应用内商品或订阅，商品 ID 必须和代码中传入的 productId 一致。
3. 配置测试轨道、许可测试账号和测试付款环境。
4. 确认应用通过 Google Play 安装或在支持 Google Play Billing 的测试环境运行。
5. Android 需要 com.android.vending.BILLING 权限，本插件已在 app-android/AndroidManifest.xml 中声明。
6. 查询 Android 商品时建议明确传 productTypes。Google Play 的一次性商品底层都是 inapp，插件无法仅凭平台数据判断它是消耗型还是非消耗型。

iOS / App Store 准备

1. 使用 Apple Developer Program 账号，完成 App Store Connect 中的协议、税务和银行信息。
2. 创建 App，Bundle ID 必须和 iOS 应用一致。
3. 在 App Store Connect 创建 App 内购买项目或订阅，商品 ID 必须和代码中传入的 productId 一致。
4. 配置价格、销售范围、审核信息和本地化信息。
5. 配置沙盒测试账号或使用 TestFlight 测试。
6. 本插件使用 StoreKit2，最低支持 iOS 15。
7. 如果使用 ios.appAccountToken，必须传 UUID 字符串。

HarmonyOS / IAP Kit 准备

1. 在 AppGallery Connect / HarmonyOS 相关后台创建应用，包名、签名和应用信息需要与工程一致。
2. 开通并配置 IAP Kit。
3. 创建商品并确认商品类型：
   • CONSUMABLE
   • NONCONSUMABLE
   • AUTORENEWABLE
4. 配置沙盒测试账号和测试环境。
5. 购买前建议调用 isSupported 做环境诊断，提前发现账号、地区、服务环境或配置问题。
6. 购买成功后需要解析并保存订单凭证，业务发货成功后调用 finish 或 consume 完成订单。

安装和导入

将插件放入项目的 uni_modules/tt-iap-sdk 后使用：

import * as iapSdk from '@/uni_modules/tt-iap-sdk'

const iap = iapSdk.getTTIap()

getTTIap() 返回 TTIap 统一接口：

iap.isSupported(...)
iap.getProducts(...)
iap.purchase(...)
iap.getPendingPurchases(...)
iap.restore(...)
iap.consume(...)
iap.finish(...)

底层平台桥接接口仅用于插件内部适配，业务代码不要直接依赖。

商品类型

iapSdk.IAP_PRODUCT_TYPE_CONSUMABLE      // 消耗型
iapSdk.IAP_PRODUCT_TYPE_NON_CONSUMABLE  // 非消耗型
iapSdk.IAP_PRODUCT_TYPE_SUBSCRIPTION    // 订阅

推荐业务流程

1. App 启动或进入支付页时查询待处理订单

用于补单、防止用户付款后未发货。

iap.getPendingPurchases({
  success: (purchases) => {
    purchases.forEach((purchase) => {
      // 将 purchase 交给业务服务端验单/补发货
      console.log('pending purchase:', purchase)
    })
  },
  fail: (err) => {
    console.log('query pending failed:', err)
  }
})

2. 可选环境诊断

Android 和 HarmonyOS 建议购买前调用。iOS 主要用于检查 StoreKit2 是否可用。

iap.isSupported({
  success: (supported) => {
    console.log('IAP supported:', supported)
  },
  fail: (err) => {
    console.log('IAP environment failed:', err)
  }
})

不要把 isSupported 当作唯一前置判断。真实购买仍需处理 getProducts 和 purchase 的失败回调。

3. 查询商品

Android/HarmonyOS 建议明确传入 productTypes。

iap.getProducts(['coin_001'], {
  productTypes: [iapSdk.IAP_PRODUCT_TYPE_CONSUMABLE],
  success: (products) => {
    console.log('products:', products)
  },
  fail: (err) => {
    console.log('query products failed:', err)
  }
})

4. 发起购买

iap.purchase({
  productId: 'coin_001',
  productType: iapSdk.IAP_PRODUCT_TYPE_CONSUMABLE,

  // #ifdef APP-HARMONY
  harmony: {
    developerPayload: 'order-1001'
  },
  // #endif

  // #ifdef APP-ANDROID
  android: {
    obfuscatedAccountId: 'user-1001',
    obfuscatedProfileId: 'profile-1001'
    // 订阅如需指定 offer，可传 offerToken
    // offerToken: 'xxx'
  },
  // #endif

  // #ifdef APP-IOS
  ios: {
    appAccountToken: '00000000-0000-4000-8000-000000000001'
  },
  // #endif

  success: (purchase) => {
    console.log('purchase:', purchase)
    // 只在 status 为 success/restored 时进入验单和发货流程。
    // status 为 pending 时不要 finish，等待后续 getPendingPurchases 或平台回调。
  },
  fail: (err) => {
    console.log('purchase failed:', err)
  }
})

5. 验单、发货和完成交易

购买成功后，建议流程是：

1. 把 purchase 中的 purchaseToken、receipt、signature、orderId、transactionId、productId、productType 上传到业务服务端。
2. 服务端向对应平台做验单或验签。
3. 服务端幂等发货或发放权益。
4. 客户端收到业务发货成功结果后，再调用 consume 或 finish。

消耗型商品：

iap.consume({
  productId: purchase.productId,
  productType: purchase.productType,
  purchaseToken: purchase.purchaseToken ?? '',
  orderId: purchase.orderId,
  transactionId: purchase.transactionId,
  success: () => {
    console.log('consume success')
  },
  fail: (err) => {
    console.log('consume failed:', err)
  }
})

非消耗型和订阅：

iap.finish({
  productId: purchase.productId,
  productType: purchase.productType,
  purchaseToken: purchase.purchaseToken,
  orderId: purchase.orderId,
  transactionId: purchase.transactionId,
  success: () => {
    console.log('finish success')
  },
  fail: (err) => {
    console.log('finish failed:', err)
  }
})

6. 恢复已购

用于非消耗型商品和订阅，不适合消耗型商品。

iap.restore({
  productTypes: [
    iapSdk.IAP_PRODUCT_TYPE_NON_CONSUMABLE,
    iapSdk.IAP_PRODUCT_TYPE_SUBSCRIPTION
  ],
  success: (purchases) => {
    console.log('restored:', purchases)
  },
  fail: (err) => {
    console.log('restore failed:', err)
  }
})

结果字段说明

IAPProduct

IAPPurchaseResult

错误码

平台差异和注意事项

Android

• 插件已声明 com.android.vending.BILLING 权限。
• purchase 内部会防止并发购买；上一次购买未返回前再次购买会失败。
• 查询一次性商品时，Google Play 只返回 inapp 类型，业务必须通过 productTypes 区分消耗型和非消耗型。
• 订阅商品如果不传 android.offerToken，插件默认使用商品返回的第一个订阅 offer。
• 消耗型商品必须在业务发货成功后调用 consume，否则可能无法再次购买。
• 非消耗型和订阅需要在发货或权益确认后调用 finish。

iOS

• 插件基于 StoreKit2，要求 iOS 15+。
• ios.appAccountToken 必须是 UUID 字符串；不是 UUID 时 StoreKit 不会使用该参数。
• iOS 的 purchaseToken 是插件当前进程内用于 finish 的交易缓存 key，不是服务端验单 token。
• App 重启后如果需要完成未完成交易，先调用 getPendingPurchases 重新取回交易。
• restore 会触发 App Store 恢复流程并返回当前有效权益。
• StoreKit 商品查询不到时，通常需要检查 App Store Connect 商品状态、Bundle ID、商品 ID、协议税务银行信息、沙盒账号或 TestFlight 环境。

HarmonyOS

• 建议购买前调用 isSupported 做 IAP Kit 环境诊断。
• purchase 通过 harmony.developerPayload 透传业务参数。
• purchaseData 中包含平台订单数据，业务应保存并上传服务端验签/验单。
• 发货成功后调用 finish 或 consume，避免掉单和重复发货。
• 当前 getPendingPurchases 基于平台当前权益查询，和 iOS/Android 的 unfinished 语义不完全一致，请结合业务服务端订单状态做补单。

常见问题

为什么商品查询为空？

优先检查：

• 商品 ID 是否和平台后台完全一致。
• 商品类型是否传错，尤其 Android/HarmonyOS 的 productTypes。
• App 包名/Bundle ID 是否和平台后台应用一致。
• 商品是否已保存、激活、可售、通过审核或处于可测试状态。
• 测试账号和测试渠道是否正确。
• iOS 是否完成 App Store Connect 协议、税务、银行信息。

为什么购买成功后还需要 consume 或 finish？

平台需要知道这笔订单已经被业务处理完成：

• 消耗型商品完成后才能再次购买。
• 非消耗型和订阅完成后可减少重复回调和待处理订单。
• 应在服务端验单和发货成功后再调用，不能在购买回调里无条件调用。

为什么 iOS 环境诊断不是必须？

iOS 当前只检查 StoreKit2 是否可用。真实购买可用性仍取决于商品配置、账号、沙盒/TestFlight 环境和 App Store Connect 状态。Android/HarmonyOS 的环境诊断更适合购买前做前置检查。

插件是否包含服务端验单？

不包含。插件只提供客户端凭证字段。生产环境应由业务服务端完成验单、幂等发货、订阅权益计算、退款/撤销处理和风控。

发布前测试建议

三端至少回归以下场景：

• 可选环境诊断：isSupported
• 商品查询：消耗型、非消耗型、订阅
• 商品 ID 错误或商品未配置
• 购买成功
• 用户取消购买
• pending / deferred 订单
• 消耗型商品发货后 consume
• 非消耗型和订阅发货后 finish
• App 重启后 getPendingPurchases
• 非消耗型和订阅 restore
• 重复点击购买
• 网络异常、平台账号异常、测试账号异常

参考资料

• Apple App Store Connect In-App Purchase 配置：https://developer.apple.com/help/app-store-connect/configure-in-app-purchase-settings/overview-for-configuring-in-app-purchases/
• Apple In-App Purchase：https://developer.apple.com/in-app-purchase/
• Google Play 创建应用内商品：https://support.google.com/googleplay/android-developer/answer/1153481
• HarmonyOS IAP Kit 使用入门：https://developer.harmonyos.cool/docs/dev/app-dev/application-services/iap-kit-guide/iap-dev-guide