更新记录

1.0.0（2026-02-06） 下载此版本

• 初始版本
• 支持检查IAP环境
• 支持查询商品信息
• 支持发起购买
• 支持查询未完成订单
• 支持确认发货

平台兼容性

uni-app(4.82)

jack-iap

华为鸿蒙 IAP Kit 应用内支付插件，为 uni-app 开发者提供便捷的鸿蒙应用内支付能力。

功能特性

• ✅ 检查 IAP 环境可用性
• ✅ 查询商品信息
• ✅ 发起购买（拉起华为收银台）
• ✅ 查询未完成订单（补单机制）
• ✅ 确认发货完成购买
• ✅ 沙盒测试环境检查
• ✅ 完整的错误码处理

平台支持

前置条件

1. 在 AppGallery Connect 创建应用并开通 IAP 服务
2. 在 AGC 后台配置商品信息（商品类型：非续期订阅）
3. 添加沙盒测试账号（开发调试阶段）
4. 使用 debug 签名进行沙盒测试

安装

在 uni-app 插件市场搜索 jack-iap 导入项目，或直接将插件目录复制到 uni_modules 下。

快速开始

1. 引入插件

// #ifdef APP-HARMONY
import { 
  checkIapEnvironment,
  queryProducts,
  createPurchase,
  queryUnfinishedPurchases,
  finishPurchase,
  checkSandboxActivated,
  IAPErrorCode
} from '@/uni_modules/jack-iap'
// #endif

2. 检查 IAP 环境

在使用支付功能前，必须先检查当前环境是否支持 IAP：

checkIapEnvironment({
  success: () => {
    console.log('IAP 环境可用')
    // 可以显示支付相关功能
  },
  fail: (err) => {
    console.log('IAP 环境不可用:', err)
    // 隐藏支付相关入口
  }
})

⚠️ 目前 IAP Kit 仅支持中国大陆地区（港澳台除外）

3. 查询商品信息

从 AGC 后台获取商品详情，用于展示价格等信息：

queryProducts({
  productIds: ['your_product_id_1', 'your_product_id_2'],
  success: (products) => {
    console.log('商品列表:', products)
    // products 结构：
    // [{
    //   productId: 'xxx',
    //   productName: '商品名称',
    //   productDesc: '商品描述',
    //   price: '18.00',
    //   currency: 'CNY'
    // }]
  },
  fail: (err) => {
    console.log('查询商品失败:', err)
  }
})

4. 发起购买

调用后会拉起华为收银台：

createPurchase({
  productId: 'your_product_id',
  quantity: 1,  // 可选，默认为1，最大10
  success: (result) => {
    console.log('购买成功:', result)
    // result 结构：
    // {
    //   purchaseToken: 'xxx',
    //   purchaseOrderId: 'xxx',
    //   productId: 'xxx',
    //   productType: 2,
    //   quantity: 1,
    //   purchaseTime: 1234567890,
    //   jwsPurchaseOrder: 'xxx'  // JWS格式订单数据，需发送到服务端验签
    // }

    // 处理发货逻辑...
  },
  fail: (err, code) => {
    console.log('购买失败:', err, code)

    // 特殊错误码需要检查补单
    if (code === IAPErrorCode.PRODUCT_OWNED || code === IAPErrorCode.SYSTEM_ERROR) {
      // 调用 queryUnfinishedPurchases 检查是否需要补单
    }
  }
})

5. 查询未完成订单（补单）

用于处理掉单场景，建议在应用启动时和页面 onShow 时调用：

queryUnfinishedPurchases({
  success: (purchases) => {
    if (purchases.length > 0) {
      console.log('发现未完成订单:', purchases.length)
      // 遍历处理每个未完成订单
      purchases.forEach(purchase => {
        // 1. 调用服务端发货
        // 2. 发货成功后调用 finishPurchase
      })
    }
  },
  fail: (err) => {
    console.log('查询未完成订单失败:', err)
  }
})

6. 确认发货

发货成功后必须调用此方法通知华为：

finishPurchase({
  productType: 2,  // 非续期订阅商品
  purchaseToken: result.purchaseToken,
  purchaseOrderId: result.purchaseOrderId,
  success: () => {
    console.log('确认发货成功')
  },
  fail: (err) => {
    console.log('确认发货失败:', err)
  }
})

⚠️ 必须在发货成功后再调用 finishPurchase，否则可能导致用户付款但未收到权益

7. 沙盒测试检查（可选）

开发调试时检查沙盒环境是否配置正确：

checkSandboxActivated({
  success: (isActivated) => {
    console.log('沙盒环境:', isActivated ? '已激活' : '未激活')
  },
  fail: (err, code) => {
    console.log('沙盒检查失败:', err)
    // 常见错误：
    // 1001860057 - 应用签名不是 debug
    // 1001860058 - 当前账号不是测试账号
    // 1001860050 - 华为账号未登录
  }
})

完整示例

export default {
  data() {
    return {
      iapAvailable: false
    }
  },

  onLoad() {
    this.initIap()
  },

  onShow() {
    this.checkUnfinishedPurchases()
  },

  methods: {
    // 初始化
    initIap() {
      // #ifdef APP-HARMONY
      checkIapEnvironment({
        success: () => {
          this.iapAvailable = true
        },
        fail: (err) => {
          this.iapAvailable = false
        }
      })
      // #endif
    },

    // 补单检查
    checkUnfinishedPurchases() {
      // #ifdef APP-HARMONY
      queryUnfinishedPurchases({
        success: (purchases) => {
          purchases.forEach(p => this.processPurchase(p))
        }
      })
      // #endif
    },

    // 处理购买结果
    async processPurchase(result) {
      // 1. 调用服务端发货
      const res = await yourApi.deliver({
        productId: result.productId,
        purchaseToken: result.purchaseToken,
        purchaseOrderId: result.purchaseOrderId,
        jwsPurchaseOrder: result.jwsPurchaseOrder
      })

      // 2. 发货成功后确认
      if (res.success) {
        // #ifdef APP-HARMONY
        finishPurchase({
          productType: result.productType,
          purchaseToken: result.purchaseToken,
          purchaseOrderId: result.purchaseOrderId,
          success: () => {
            uni.showToast({ title: '购买成功' })
          }
        })
        // #endif
      }
    },

    // 发起购买
    handlePurchase(productId) {
      // #ifdef APP-HARMONY
      if (!this.iapAvailable) {
        uni.showToast({ title: '支付服务不可用', icon: 'none' })
        return
      }

      createPurchase({
        productId,
        success: (result) => {
          this.processPurchase(result)
        },
        fail: (err, code) => {
          if (code === IAPErrorCode.PRODUCT_OWNED || code === IAPErrorCode.SYSTEM_ERROR) {
            this.checkUnfinishedPurchases()
          }
        }
      })
      // #endif
    }
  }
}

API 参考

checkIapEnvironment(options)

检查 IAP 环境是否可用。

queryProducts(options)

查询商品信息。

ProductInfo 结构：

createPurchase(options)

发起购买，拉起收银台。

PurchaseResult 结构：

queryUnfinishedPurchases(options)

查询未完成的购买订单。

finishPurchase(options)

确认发货，完成购买流程。

checkSandboxActivated(options)

检查沙盒测试环境是否激活。

IAPErrorCode

错误码常量。

支付流程说明

用户点击购买
    ↓
checkIapEnvironment() 检查环境
    ↓
createPurchase() 拉起收银台
    ↓
用户完成支付
    ↓
收到 PurchaseResult
    ↓
调用服务端发货接口
    ↓
发货成功
    ↓
finishPurchase() 确认发货
    ↓
完成

补单机制

为防止掉单（用户付款但 App 未收到回调），需要在以下时机调用 queryUnfinishedPurchases：

1. 应用启动时
2. 支付页面 onShow 时
3. createPurchase 返回 PRODUCT_OWNED 或 SYSTEM_ERROR 错误时

常见问题

Q: 收银台没有拉起？

检查：

• checkIapEnvironment 是否返回成功
• 商品ID是否在 AGC 后台配置且已生效
• 华为账号是否已登录

Q: 沙盒测试失败？

检查：

• 是否使用 debug 签名
• 当前华为账号是否添加到 AGC 沙盒测试账号列表

Q: finishPurchase 失败会影响用户吗？

如果发货已成功，finishPurchase 失败不影响用户权益，但会导致用户无法再次购买同一商品。

相关链接

• 华为 IAP Kit 官方文档
• AppGallery Connect 控制台

更新日志

1.0.0

• 初始版本
• 支持非续期订阅商品购买
• 支持补单机制
• 支持沙盒测试检查

许可证

MIT License

作者

鸿蒙Jack