HarmonyOS IAP 内购集成与沙箱测试

IAP（In-App Purchase）是鸿蒙应用变现的关键能力。NetLab 采用"免费 + ¥5 解锁"模式，本文分享 IAP 集成全流程和沙箱测试踩坑经验，帮你少走弯路。

一、AGC 后台准备

1. 签署 IAP 协议：AGC → 我的项目 → 常规 → 变现 → IAP → 签署协议
2. 创建商品：IAP → 商品管理 → 添加商品
   • 商品ID：unlock_all_experiments（自定义，代码中引用）
   • 商品类型：非消耗型（一次购买永久有效，适合解锁功能）
   • 价格：¥5（华为定价档位，不能自定义任意金额）
   • 商品名称/描述：多语言配置
3. 沙箱测试账号：AGC → 我的项目 → 常规 → 应用信息 → 沙箱测试

二、代码集成 IAP Kit

2.1 导入模块

import { iap } from '@kit.IAPKit';

2.2 发起购买

async function purchaseUnlock() {
  try {
    const purchaseResult = await iap.purchase({
      productId: 'unlock_all_experiments',
    });
    // 购买成功
    console.info('IAP purchase success:', purchaseResult);
    saveUnlockStatus(true);  // 本地标记解锁
  } catch (error) {
    console.error('IAP purchase failed:', error.code, error.message);
    if (error.code === 600004) {
      // 用户取消购买
    }
  }
}

2.3 恢复购买（换设备）

async function restorePurchase() {
  try {
    const result = await iap.getAvailableProducts({
      productIds: ['unlock_all_experiments']
    });
    if (result.length > 0) {
      // 已购买，恢复解锁状态
      saveUnlockStatus(true);
    }
  } catch (error) {
    console.error('Restore failed:', error);
  }
}

换设备登录同一华为账号，调用 restorePurchase() 即可恢复解锁，无需重复付费。

三、沙箱测试（重点坑点）

这是我踩坑最多的环节，分享真实经历：

3.1 沙箱测试流程

1. 真机登录沙箱测试华为账号（非开发者账号）
2. 安装 debug 包（DevEco Studio Run 到真机）
3. 触发购买，应弹出华为支付沙箱页面
4. 沙箱支付无需真实扣款，模拟成功即可

3.2 坑点一：debug 包无法跳转支付

解决方案：① 沙箱测试需用 Release 签名包安装到真机 ② 或等应用上架后，从应用市场下载正式版测试 ③ 我最终选择等审核通过后在正式环境验证，支付流程正常

3.3 坑点二：沙箱测试账号需一致

真机登录的华为账号必须与 AGC 沙箱测试名单中的账号一致，否则无法识别为沙箱测试，会走正式支付流程（真实扣款）。

3.4 坑点三：测试间隔限制

沙箱测试同一商品有购买间隔限制（约10分钟），频繁测试需等待或清除测试记录。

四、正式环境验证

应用上架后，用真实华为账号下载正式版验证：

验证清单:
✅ 点击解锁 → 弹出华为支付页面（真实支付UI）
✅ 支付¥5 → 支付成功 → 解锁全部实验
✅ 杀进程重进 → 解锁状态保持（本地持久化）
✅ 卸载重装 → 调restorePurchase → 解锁恢复
✅ 换设备登录同账号 → 解锁自动恢复
✅ 非消耗型：重复点击解锁 → 提示"已购买"，不重复扣款

五、经验总结

• 商品类型选对：解锁功能用非消耗型，一次购买永久有效
• debug 环境限制：IAP 在 debug 包下无法跳转支付，需 Release 包或正式版测试
• 恢复购买必做：换设备场景调用 restorePurchase，否则用户投诉
• 沙箱账号一致：真机登录账号必须与 AGC 沙箱名单一致
• 本地持久化解锁状态：避免每次启动都查询，提升体验

NetLab 的 IAP 已上线并验证通过，¥5 解锁全部实验，换设备自动恢复。下一篇分享 AGC 上架审核全流程。