更新记录

1.0.0（2026-02-04）

• 初版发布
• 支持 Android Google Play Billing（PBL 8.x）：初始化、查询商品、发起购买、消耗、确认、查询已购
• 内置本地 AAR 依赖，兼容云打包场景

平台兼容性

uni-app(4.52)

uni-app x(4.52)

jwh-GooglePay

Google Play Billing（Google 内购/订阅）UTS 插件，面向 uni-app x。

特性

• 基于 Google Play Billing Library（PBL）8.x
• 支持 内购（inapp） / 订阅（subs）
• 内置本地 AAR 依赖，避免云打包拉取 Maven 失败
• 支持完整流程：初始化、查询商品、发起购买、消耗、确认、查询已购
• 失败回调返回统一错误码与中文说明

支持平台

• Android（uni-app x）
• iOS / Harmony：暂不支持

前置条件

• Android minSdkVersion >= 21
• 设备需具备并可用：Google Play 商店、Google Play 服务（GMS）
• 开发/测试建议使用：
  • 真机：已认证且带完整 GMS 的设备
  • 模拟器：Android Studio AVD 的 “Google Play” 系统镜像

权限说明

插件默认声明：

• android.permission.INTERNET
• com.android.vending.BILLING

目录结构

• utssdk/app-android/libs/billing8.aar: Google Play Billing AAR（已内置）
• utssdk/interface.uts: 接口定义
• utssdk/unierror.uts: 错误码定义
• utssdk/app-android/index.uts: Android 原生实现

安装与使用

1. 安装插件

将插件安装到 uni_modules/jwh-GooglePay 后即可使用。

2. Play Console 配置（非常重要）

Google 内购/订阅必须在 Play Console 配置完成并满足测试条件，否则会出现商品不可用、计费服务不可用、无法拉起收银台等问题。

建议检查：

• 已创建应用并完成基础信息
• 已创建并激活商品（inapp/subs），商品 ID 与代码一致
• 应用已上传到测试轨道（内部测试/封闭测试等）
• 测试账号已加入测试人员列表，并在设备 Play 商店登录该账号
• 设备区域/商品销售区域匹配

3. 基本流程

推荐顺序： 1) initBilling
2) queryProducts（缓存 ProductDetails）
3) launchPurchase
4) 成功后：

• inapp：consumePurchase（消耗型道具）或按业务处理
• subs：acknowledgePurchase（确认订阅） 5) 可选：queryPurchases 恢复/查询已购

1. 初始化

import { initBilling } from '@/uni_modules/jwh-GooglePay';

initBilling({
  success: () => {
    console.log("初始化成功");
  },
  fail: (err) => {
    console.error("初始化失败", err);
  }
});

2. 查询商品

import { queryProducts } from '@/uni_modules/jwh-GooglePay';

queryProducts({
  productIds: ['your_product_id'],
  productType: 'inapp', // 或 'subs'
  success: (products) => {
    console.log("商品详情", products);
  }
});

3. 发起购买

import { launchPurchase } from '@/uni_modules/jwh-GooglePay';

launchPurchase({
  productId: 'your_product_id',
  productType: 'inapp',
  success: (res) => {
    console.log("购买成功", res);
    // 接下来需要消耗或确认
  }
});

4. 消耗/确认购买

注意：购买完成后需要按产品类型执行 消耗（consume） 或 确认（acknowledge）。建议在服务端校验购买凭证后再发放权益。

import { consumePurchase, acknowledgePurchase } from '@/uni_modules/jwh-GooglePay';

// 内购项目 (消耗)
consumePurchase({
  purchaseToken: '...',
  success: (token) => console.log("消耗成功")
});

// 订阅项目 (确认)
acknowledgePurchase({
  purchaseToken: '...',
  success: (token) => console.log("确认成功")
});

API 说明

initBilling(options)

• 作用：初始化并连接 BillingClient
• 常见失败：设备无 GMS、Play 服务不可用、网络不可达等

queryProducts(options)

• 作用：查询商品详情（并缓存 ProductDetails 用于购买流程）
• 参数：
  • productIds: string[]
  • productType: "inapp" | "subs"
• 返回：ProductDetails[]（包含 _raw 字段）

launchPurchase(options)

• 作用：发起购买
• 注意：
  • 必须先 queryProducts，插件会从缓存里取 ProductDetails
  • 订阅（subs）需要传 offerToken

consumePurchase(options)

• 作用：消耗购买（通常用于消耗型道具）

acknowledgePurchase(options)

• 作用：确认购买（订阅/不可消耗产品通常需要确认）

queryPurchases(options)

• 作用：查询当前账号下已购买项目（恢复购买/校对权益）

错误码与失败原因（中文）

插件的失败回调统一返回 UniError（包含 errCode / errMsg）。其中：

• errCode：尽量与 Google Play Billing 的 BillingResponseCode 保持一致；另外提供了 9 开头的自定义错误码。
• errMsg：默认会从 utssdk/unierror.uts 中的 BillingErrors 映射取中文；如果 Google 返回了 debugMessage，会尽量翻译为中文并拼接说明（少量情况仍可能保留英文原文）。

常见 errCode 对照

订阅 offerToken 如何获取

订阅商品购买通常需要指定 offer。插件的 queryProducts 返回的 ProductDetails 中包含 _raw（原始 Google ProductDetails 对象）。

示例思路： 1) queryProducts 得到 products 2) 取 products[0]._raw.subscriptionOfferDetails 3) 选择一个 offer（例如第一个），并读取其 offerToken 4) 在 launchPurchase 时传入 offerToken

常见问题（排查）

云打包失败 / 找不到 AAR

• 确保 uni_modules/jwh-GooglePay/utssdk/app-android/libs/billing8.aar 存在

初始化失败：Billing service unavailable on device

• 设备缺少/禁用 Google Play 商店或 Google Play 服务（GMS）
• 使用 Android Studio AVD 时请选择带 “Google Play” 的系统镜像
• 第三方模拟器（含部分 MuMu 版本）通常不稳定或不可用，建议换真机或 AVD

无法调起支付/收银台

• 检查 Play Console：测试轨道、测试账号、商品状态、区域是否匹配
• 确保设备 Play 商店已登录测试账号，且网络可访问 Google 服务

常见编译失败原因（历史问题说明）

如果你在接入/改造过程中遇到以下编译报错，通常是因为 Billing Library 版本升级导致接口签名变化、或 UTS 对 Android List 的类型差异：

• overrides nothing / does not implement abstract member：监听器方法签名不匹配（如 ProductDetailsResponseListener 在 PBL 8 变为 QueryProductDetailsResult 参数）。
• No value passed for parameter 'p0'：enablePendingPurchases() 在新版本需要 PendingPurchasesParams 参数。
• 找不到名称 length：Android List 在 UTS/Kotlin 侧应使用 .size 而不是 .length。

如何更新 Billing AAR

本插件内置 billing8.aar，如果你需要升级到更高版本，可从 Google Maven 下载对应版本的 AAR，并替换 utssdk/app-android/libs/billing8.aar。