HarmonyOS IAP Kit让你的应用支持应用内购买什么是 IAP Kit你玩游戏的时候是不是经常会看到购买钻石、购买皮肤之类的按钮你点一下弹出一个支付界面付完钱东西就到手了。这就是应用内购买In-App Purchase简称 IAP。IAP Kit 就是 HarmonyOS 提供的应用内购买工具。你不需要自己搭支付系统不需要对接银行只需要用 IAP Kit 提供的接口就能让你的 App 支持用户在里面买东西。买什么呢比如游戏里买道具、买钻石、买皮肤比如视频 App 里买会员比如工具 App 里解锁高级功能。只要是在 App 里面发生的购买行为都可以用 IAP Kit 来实现。商品类型IAP Kit 支持三种商品类型每种类型的用途不一样消耗型商品用完了可以再买的那种。最典型的例子就是游戏里的钻石、金币。你买了 100 钻石用完了可以再买 100 钻石。这种商品的特点是用完即消所以叫消耗型。非消耗型商品买一次就永久拥有的那种。比如你买了一个游戏的额外关卡买了就是你的不用再花钱。再比如你买了一个 App 的永久会员一次付费终身使用。这种商品买了之后就不会再扣费了。自动续期订阅商品按月或者按年自动续费的那种。最典型的就是视频会员、音乐会员。你买了月度会员每个月自动扣费直到你取消为止。这种商品的好处是能给开发者带来持续的收入。环境搭建硬件要求设备类型华为手机HarmonyOS 系统HarmonyOS 5.0.5 Release 及以上软件要求DevEco Studio 版本DevEco Studio 6.1.0 Release 及以上HarmonyOS SDK 版本HarmonyOS 6.1.0 Release SDK 及以上前置准备在写代码之前你需要先在华为开发者后台做一些配置。这些配置不做的话代码写了也跑不起来。开通商户服务首先你得去 AppGallery Connect华为开发者后台开通商户服务。这一步是告诉华为“我要开始收钱了请帮我把钱打到我的银行卡里。”具体操作是登录 AppGallery Connect → 找到你的应用 → 进入应用内购买服务 → 开通商户服务。开通过程中需要填写你的收款银行卡信息华为会把用户付的钱打到这张卡上。开启应用内购买服务商户服务开通之后还需要开启应用内购买服务。这一步是告诉华为“我的 App 要用 IAP 功能了请给我开通。”操作步骤打开应用内购买服务(HarmonyOS NEXT)开关。这个开关在 AppGallery Connect 里你的应用设置页面。激活应用内购买服务。激活之后你的 App 才能调用 IAP 的接口。配置商品商品不是在代码里定义的而是在 AppGallery Connect 的商品管理页面里配置的。你需要把你打算卖的东西一条一条添加进去。具体操作是这样的选择商品类型你要卖的是消耗型比如钻石、非消耗型比如永久会员还是订阅型比如月度会员不同类型的商品购买流程和发货逻辑会有些差别。配置商品信息给商品起个名字、写个描述。比如商品名叫100 钻石描述写购买后立即到账 100 钻石可用于游戏内消费。这些信息会展示给用户看所以写得清楚一点。配置商品价格设置这个商品卖多少钱。华为支持的价格档位是预设的你从里面选一个就行不能自己随便填一个价格。激活商品配置完之后商品默认是未激活状态你需要手动激活它。只有激活了的商品用户才能在 App 里看到和购买。如果你配置了商品但用户在 App 里看不到先检查一下是不是忘了激活。每种商品类型都有一个商品 ID这个 ID 是你自己定义的比如ohos_consume_001。在代码里查询和购买商品时用的就是这个 ID。商品 ID 一旦创建就不能改了所以取名的时候想清楚。项目结构├── entry/src/main/ets │ ├── common │ │ ├── JWSUtil.ets // JWS 工具组件用来解析购买结果 │ │ └── Logger.ets // 日志打印组件 │ ├── entryability │ │ └── EntryAbility.ets // 应用首页 ability │ └── pages │ └── ConsumablesPage.ets // 商品展示页面项目结构比较简单。JWSUtil是一个工具类用来解析购买结果里的 JWS 数据。你不需要自己写这个工具类直接用就行。第一步导入模块import{iap}fromkit.IAPKit;import{BusinessError}fromkit.BasicServicesKit;import{common}fromkit.AbilityKit;import{JWSUtil}from../common/JWSUtil;导入 IAP Kit 相关的模块iapIAP Kit 的核心接口所有的购买、查询操作都靠它BusinessError错误处理用的华为的 Kit 接口基本都用这个来返回错误common获取上下文用的调用 IAP 接口时需要传入上下文JWSUtilJWS 工具类用来解析购买结果里的加密数据第二步检查支付环境在用户购买之前先检查一下当前环境是否支持应用内支付。这一步很重要如果不支持的话后面的流程都不用走了。iap.queryEnvironmentStatus(this.getUIContext().getHostContext()ascommon.UIAbilityContext).then((){// 支持应用内支付可以继续后面的流程}).catch((error:BusinessError){// 不支持可能是地区不对或者 HMS Core 版本太低});queryEnvironmentStatus这个接口会检查用户当前登录的华为账号所在的服务地是否支持应用内支付。目前只有中国大陆支持其他地区调用会返回错误。什么时候调用这个接口呢建议在用户进入商品页面的时候就调用这样如果不支持你可以提前给用户一个提示而不是等用户点了购买按钮才发现不行。第三步查询商品信息用户进入商品页面后你需要从华为服务器查询商品的最新信息包括价格、名称、描述等。queryProducts(){letqueryProductParam:iap.QueryProductsParameter{productType:iap.ProductType.CONSUMABLE,productIds:[ohos_consume_001]};iap.queryProducts(this.context,queryProductParam).then((result){// 查询成功result.productList 里就是商品信息// 你可以把这些信息展示在页面上}).catch((error:BusinessError){// 查询失败可能是商品 ID 写错了或者商品没有激活});}queryProducts传入商品类型和商品 ID 列表返回商品的详细信息。注意productType要和你在 AppGallery Connect 里配置的商品类型一致。你配置的是消耗型这里就填CONSUMABLE。productIds是一个数组可以一次查询多个商品。里面的 ID 要和你在后台配置的商品 ID 完全一致差一个字母都不行。返回的productList里包含了每个商品的价格、名称、描述等信息你可以直接展示给用户。查询商品这一步不要跳过。虽然你在后台配置了商品信息但价格可能会调整而且你需要用返回的价格来展示给用户而不是自己硬编码一个价格。第四步发起购买用户点击购买按钮后调用createPurchase拉起华为的收银台。asyncbuy(id:string,type:iap.ProductType){try{letcreatePurchaseParam:iap.PurchaseParameter{productId:id,productType:type,};iap.createPurchase(this.context,createPurchaseParam).then(async(result){// 购买成功解析购买结果letjwsPurchaseOrder:stringJSON.parse(result.purchaseData).jwsPurchaseOrder;letpurchaseStrJWSUtil.decodeJwtObj(jwsPurchaseOrder);letpurchaseOrderPayloadJSON.parse(purchaseStr)asPurchaseOrderPayload;this.finishPurchase(purchaseOrderPayload);}).catch((error:BusinessError){// 购买失败或用户取消// error.code 1001860002 表示用户取消了购买// 其他错误码表示购买过程中出了问题});}catch(error){// 参数错误等异常情况}}createPurchase会弹出华为的收银台界面用户在里面确认支付。这个过程是华为控制的你不需要自己做支付界面。用户支付成功后result.purchaseData里会包含购买结果。但这个结果是 JWS 格式的一种加密签名格式你需要用JWSUtil来解析它。解析之后你会得到一个PurchaseOrderPayload对象里面包含了商品 ID、购买订单号、购买令牌等信息。拿到这些信息后你需要做两件事发放权益比如给用户充钻石、解锁会员功能调用finishPurchase告诉华为我已经发货了这两件事做完一次购买流程才算完整。第五步完成购买发放权益之后一定要调用finishPurchase告诉华为我发货了。finishPurchase(purchaseOrder:PurchaseOrderPayload){letfinishPurchaseParam:iap.FinishPurchaseParameter{productType:purchaseOrder.productType,purchaseToken:purchaseOrder.purchaseToken,purchaseOrderId:purchaseOrder.purchaseOrderId};iap.finishPurchase(this.context,finishPurchaseParam).then((result){// 购买完成整个流程结束// 用户可以再次购买该商品了}).catch((error:BusinessError){// 完成购买失败需要重试});}为什么要调用这个接口因为如果你不调用华为会认为你还没发货用户就没办法再次购买同一个消耗型商品。比如用户买了 100 钻石你给充了但没调finishPurchase那用户下次想再买 100 钻石就买不了了华为会提示你已经购买过该商品。所以这个接口一定要调而且要在确认发货成功之后再调。如果你先调了finishPurchase再发货万一发货失败了用户钱付了但东西没到手那就麻烦了。第六步处理掉单掉单是支付场景里一个很常见的问题。简单说就是用户付了钱但因为网络问题、App 闪退等原因你没收到支付成功的通知导致你没给用户发货。这种情况如果不管的话用户会投诉我钱扣了但东西没到所以你必须处理掉单。怎么处理呢在以下场景调用queryPurchases查询有没有未发货的购买asyncqueryPurchases(){letparam:iap.QueryPurchasesParameter{productType:iap.ProductType.CONSUMABLE,queryType:iap.PurchaseQueryType.UNFINISHED};iap.queryPurchases(this.context,param).then((res:iap.QueryPurchaseResult){letpurchaseDataList:string[]res.purchaseDataList;if(purchaseDataListundefined||purchaseDataList.length0){// 没有未完成的购买正常情况return;}// 有未完成的购买逐个处理for(leti0;ipurchaseDataList.length;i){letpurchaseDatapurchaseDataList[i];letpurchaseStrJWSUtil.decodeJwsObj(purchaseData);letpurchaseOrderPayloadJSON.parse(purchaseStr)asPurchaseOrderPayload;this.finishPurchase(purchaseOrderPayload);}}).catch((error:BusinessError){// 查询失败稍后重试});}queryPurchases会返回所有已购但未发货的商品列表。如果有你就发放权益并调用finishPurchase。你需要在以下场景检查掉单应用启动时用户可能昨天买了东西但 App 闪退了今天打开 App 时要补发购买请求返回错误码1001860001时这个错误码表示有未完成的购买购买请求返回错误码1001860051时这个错误码也表示有未完成的购买掉单处理是支付功能里非常重要的一环千万不要忽略。很多开发者上线后收到用户投诉付了钱没到账基本都是因为没做好掉单处理。完整购买流程把上面的步骤串起来整个购买流程是这样的检查环境确认用户支持应用内支付查询商品从华为服务器获取商品信息展示给用户用户点击购买调用createPurchase拉起收银台用户确认支付用户在收银台完成支付发放权益给用户充钻石、解锁功能等确认发货调用finishPurchase告诉华为发货完成处理掉单检查是否有未完成的购买补发权益适用场景IAP Kit 适合以下场景游戏应用购买游戏道具、钻石、皮肤内容应用购买课程、电子书工具应用购买高级功能会员服务购买月度/年度会员注意事项商品配置商品必须在 AppGallery Connect 上配置并激活代码里不能凭空创建商品JWS 验签购买结果是 JWS 格式的要验签确保来自华为服务器防止伪造掉单处理一定要处理掉单情况否则用户会投诉付了钱没到账发货确认发货后一定要调用finishPurchase否则用户无法再次购买消耗型商品测试环境开发时使用测试环境上线前切换到正式环境核心流程图IAP 应用内购买的完整流程否是否是在 AppGallery Connect 开通商户服务配置商品信息并激活应用启动: 检查支付环境是否支持应用内支付?提示用户当前地区不支持查询商品信息展示给用户用户点击购买调用 createPurchase 拉起收银台用户是否完成支付?用户取消或支付失败解析 JWS 购买结果发放权益给用户调用 finishPurchase 确认发货掉单处理流程否是是否应用启动调用 queryPurchases 查询未完成购买是否有未发货的购买?正常流程继续遍历未完成购买列表解析购买数据发放权益给用户调用 finishPurchase 确认发货还有更多未完成购买?掉单处理完成总结IAP Kit 让你的应用支持应用内购买核心流程在 AppGallery Connect 开通商户服务配置商品信息类型、价格、激活检查支付环境查询商品信息展示给用户发起购买拉起收银台完成购买发放权益并确认发货处理掉单确保用户权益掌握了这些你就能让你的应用支持应用内购买开始赚钱了。