《HarmonyOSNext自动续期订阅支付全攻略 | 从环境检测到防漏单指南》

《HarmonyOSNext自动续期订阅支付全攻略 | 从环境检测到防漏单指南》

##Harmony OS Next ##Ark Ts ##教育

本文适用于教育科普行业进行学习，有错误之处请指出我会修改。

---

🛍️ 一、商品展示全流程 | 单机应用也适用哦！

▸ 环境检测：先看能不能买！

当你的APP启动支付功能时，第一步必须检查用户所在地！用这个核心代码👇 向IAP Kit发起queryEnvironmentStatus请求：

import { iap } from '@kit.IAPKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

queryEnvironmentStatus() {
  const context = this.getUIContext().getHostContext() as common.UIAbilityContext;
  iap.queryEnvironmentStatus(context).then(() => {
    console.info('✅ 环境检测成功！'); 
  }).catch((err: BusinessError) => {
    console.error(`❌ 翻车了！错误码 ${err.code}，详情：${err.message}`);
    // 立刻隐藏支付入口！用户所在区域不支持支付
    this.hideIAPButtons(); 
  });
}

📣 重要提示：当前仅中国大陆支持结算！如果请求失败，请直接屏蔽支付入口避免用户困惑~

---

▸ 商品橱窗开张啦！

环境检测通过后，马上用queryProducts拉取商品信息：

queryProducts() {
  const queryProductParam: iap.QueryProductsParameter = {
    productType: iap.ProductType.AUTORENEWABLE, // 订阅型商品
    productIds: ['vip_monthly', 'premium_pack'] // ✨替换成你的商品ID！
  };
  iap.queryProducts(context, queryProductParam).then((result) => {
    console.info('🎉 商品数据到手！');
    // 在这里展示商品名称+价格，比如：
    // VIP会员 ¥25/月 | 豪华礼包 ¥68
  }).catch((err) => {
    console.error(`💥 加载失败！错误码 ${err.code}，原因：${err.message}`);  
  });
}

⚠️ 踩坑预警： 1️⃣ 每次最多查200个商品 2️⃣ 只能查​​同类型​​商品（比如全订阅或全消耗品）

---

🔍 二、权益状态检查 | 别重复卖货给老用户！

▸ 用户手里有啥订阅？

用queryPurchases查当前生效的订阅：

iap.queryPurchases(context, {
  productType: iap.ProductType.AUTORENEWABLE,
  queryType: iap.PurchaseQueryType.CURRENT_ENTITLEMENT // 生效中订单
}).then((res) => {
  const purchases = res.purchaseDataList; // 拿到订单数据(JWS格式)
  // 解析后显示订阅状态，比如："VIP会员 | 有效至2025/01/01"
});

关键操作： 👉 ​​自动续订中的商品要屏蔽购买按钮！​​（用户已有再买会报错） 👉 ​​没发货的订单要补权益​​（下面细说）

---

🚀 三、用户下单 & 结果处理

▸ 用户点击购买啦！

调createPurchase弹出收银台：

subscribe() {
  const param: iap.PurchaseParameter = {
    productType: iap.ProductType.AUTORENEWABLE,
    productId: 'vip_monthly' //✨你的商品ID
  };
  iap.createPurchase(context, param).then((result) => {
    console.info('💳 支付成功！');
    this.handleSuccess(result); // 处理成功逻辑
  }).catch((err) => {
    console.error(`💢 支付失败！错误码 ${err.code}`);
    this.handleFailure(err); // 处理失败逻辑
  })
}

📢 防封号提醒：开发阶段别狂点下单！华为会检测接口频次（错误码 1001860004）

---

▸ 情况1：购买成功！🥳

强烈建议走服务端校验！ 但客户端方案如下：

handleSuccess(result: iap.CreatePurchaseResult) {
  const jwsData = JSON.parse(result.purchaseData).jwsSubscriptionStatus;
  // 步骤1：解析订阅状态
  const payload = JWSUtil.decodeJwsObj(jwsData); 
  
  // 步骤2：检查是否生效中（status=1）
  if (payload?.lastSubscriptionStatus?.status === '1') {
    // 步骤3：发放VIP权益！（比如解锁功能）
    this.grantVipBenefits();
    
    // 步骤4：标记订单已发货👇
    this.finishPurchase(payload.lastSubscriptionStatus.lastPurchaseOrder);
  }
}

// ✅ 发货关键代码
finishPurchase(order: PurchaseOrderPayload) {
  iap.finishPurchase(context, {
    productType: Number(order.productType),
    purchaseToken: order.purchaseToken, // 交易令牌
    purchaseOrderId: order.purchaseOrderId // 订单号
  }).then(() => console.info('📦 发货完成！'))
    .catch(err => console.error(`🚚 发货失败！`, err));
}

---

▸ 情况2：购买失败...😭

重点处理两类错误：

handleFailure(err: BusinessError) {
  // 错误1：用户已购买（PRODUCT_OWNED）
  // 错误2：系统抽风（SYSTEM_ERROR）
  if (err.code === iap.IAPErrorCode.PRODUCT_OWNED || 
      err.code === iap.IAPErrorCode.SYSTEM_ERROR) {
    this.checkMissingOrders(); // 检查漏单补权益！
  }
}

---

🧩 【模块扩展】漏单自动补货攻略

网络闪退？支付卡单？用这个神器👇 自动检测未发货订单：

checkMissingOrders() {
  iap.queryPurchases(context, {
    productType: iap.ProductType.AUTORENEWABLE,
    queryType: iap.PurchaseQueryType.UNFINISHED // ⭐专查未发货订单！
  }).then((res) => {
    res.purchaseDataList.forEach(order => {
      const payload = decodeJws(order); // 解析订单
      if (payload.status === '1') { // 状态有效
        this.grantVipBenefits(); // 补发权益！
        this.finishPurchase(payload); // 标记发货
      }
    });
  });
}

---

🎯 四、单机应用特殊关怀

如果你是纯客户端应用（无服务端）：

🔹 环境检测 + 商品展示逻辑完全一致 🔹 权益发放后​​必须调用​​finishPurchase 🔹 建议将​​用户权益​​与​​订阅状态绑定​​： → 用户有有效订阅？✅ 持续给权益！ → 订阅过期？⛔ 关闭权益！

---

💎 核心要点总结表

步骤	关键操作	代码	注意事项
✅ 环境检测	判断是否支持支付	queryEnvironmentStatus	失败时隐藏支付入口！
🛍️ 商品展示	获取商品信息列表	queryProducts	最多200个/次
🔍 订阅状态检查	屏蔽已购商品按钮	queryPurchases	自动续费商品不可再买
🚀 用户下单	弹出华为收银台	createPurchase	控制测试频次！
📦 发货标记	权益发放后调用	finishPurchase	防止重复扣款
🧩 漏单处理	定期查询未发货订单	queryPurchases+UNFINISHED	自动补权益

✨ 一句话口诀： ​​先查环境→展示商品→检查已有→下单发货→漏单补刀​​ 跟着流程走，支付系统稳如狗！ 🐶