《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
🔹 建议将​​用户权益​​与​​订阅状态绑定​​：
→ 用户有有效订阅？✅ 持续给权益！
→ 订阅过期？⛔ 关闭权益！

💎 核心要点总结表

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