更新记录

0.1.1（2026-11-07）

• 优化说明文档，补齐“作者系列 UTS 插件”清单及插件市场链接，便于按能力查找。

0.1.0（2026-11-06）

• 新增 Google Play Billing 9.1.0 官方依赖、Android API23+ 原生桥接和公共 UTS 合同。
• 新增商品/报价查询、一次性购买、订阅换档、当前购买查询及分组恢复。
• 新增显式确认/消耗、连接与购买事件、能力检测、订阅消息和管理入口。
• 新增有界脱敏诊断及 uni-app Vue2/Vue3、uni-app x 同源示例，支持完整报告、固定快照分段和复制失败回退。
• 新增服务端核验、幂等发货和真实 Play 验收边界说明；候选源码不表示已上架或真实交易已验收。
• 修复 Android 开发编译中公共运行时缺少显式 UTSAndroid 导入导致的 JSON/typeof 未解析及后续类型错误，保留原有接口、解析校验和回调合同。
• 修复 Android 云打包依赖图读取旧版 play-services-places-placereport 元数据失败：通过 Gradle 依赖对象排除插件未使用的定位传递链，保留 Billing 9.1.0 及其余官方依赖。
• 修复 iOS 不支持平台入口的日志表达式和终态闭包类型推断错误，继续返回明确不支持错误。
• 修复 iOS 不支持入口的诊断日期及数值、布尔日志转换，不改变真实不支持错误。

平台兼容性

uni-app(5.33)

uni-app x(5.33)

lizhao-play-billing · Google Play 内购与订阅

介绍

面向 uni-app Vue2/Vue3 和 uni-app x 的 Android Google Play Billing UTS 插件，使用 Google 官方 Billing Library 9.1.0，提供商品查询、购买、订阅换档、恢复购买及显式确认/消耗。

当前为候选源码。客户端取得购买凭据后仍须可信后端验单和幂等发货。资源编译、本地行为测试与原生编译均不能替代 Play 测试账号下的实际交易验收；不宣称已在插件市场上架。

功能特色

• queryProducts 返回全部可见报价和价格阶段，以及未取回商品的原因；金额微单位用十进制字符串保留精度。
• launchPurchase 在拉起前重新查询商品并检查原选报价，避免缓存过期后悄悄选择另一价格。成功只表示 SDK 接受拉起。
• onPurchasesUpdated 独立传递购买状态；PENDING 转 PURCHASED 不会因 token 相同被丢弃。
• restorePurchases 同时查询一次性商品和订阅，保留每组结果及错误，单边失败明确返回部分结果。
• acknowledgePurchase、consumePurchase 均由业务显式调用；插件不自动发货、不自动确认或消耗。
• 连接合并、代际隔离、超时结果未知和前台恢复查询减少重复交易风险；监听可按 ID 释放。
• 双宿主示例含完整环境报告、原生诊断、脱敏日志、一键复制、固定快照分段及手动复制回退。

适合哪些场景

下载与导入

保留完整 uni_modules/lizhao-play-billing/ 目录，通过源码方式导入项目。业务仅从 @/uni_modules/lizhao-play-billing 根目录导入 API；不要导入内部平台文件。

在宿主 pages.json 注册对应页面。选择当前宿主示例，不把 uvue 页面直接注册到传统 uni-app。源码基于 HBuilderX 5.33 系列验证；Android 最低 API 23。导入包含新的原生 UTS/Kotlin 和 Maven 依赖，必须重新原生联编或制作 Android 自定义基座；标准基座及旧基座不能凭 WGT 获得新增 SDK。

原生配置位于 uni_modules/lizhao-play-billing/utssdk/app-android/config.json。配置通过 HBuilderX 支持的 Gradle 源码对象固定使用 com.android.billingclient:billing:9.1.0，并排除该版本 POM 带入的 com.google.android.gms:play-services-location 旧传递链；插件本身不调用定位 API。这样可避免继续解析 play-services-places-placereport:17.0.0，同时保留 Billing API 及其余官方依赖。插件不附带 AAR/JAR，不需要把 SDK 手工复制进项目。

从基础到进阶：按业务模块使用

模块一：连接和事件生命周期

先在 Google Play Console 准备应用、真实商品及测试账号，Android 包名须与对应应用一致。uni-app x 页面可直接使用以下最小连接示例；它不会发起购买或发货：

<template>
  <view>
    <button @click="connect">连接 Play</button>
    <text>{{ status }}</text>
  </view>
</template>
<script setup lang="uts">
import { ref } from 'vue'
import { connectBilling, onPurchasesUpdated, offPurchasesUpdated, BillingEvent } from '@/uni_modules/lizhao-play-billing'
const status = ref('尚未连接')
const listenerId = onPurchasesUpdated((event: BillingEvent) => {
  status.value = '购买事件：' + event.purchases.length + ' 条，须按状态核验'
  // 将purchased购买的token通过业务HTTPS通道交可信后端；不要输出token。
})
function connect() {
  connectBilling({
    success: () => { status.value = '已连接，可查询商品' },
    fail: (error) => { status.value = error.errCode + ' · ' + error.errMsg },
    complete: (result) => { console.log('连接完成：' + result.requestId + '，ok=' + result.ok) }
  })
}
onUnload(() => { offPurchasesUpdated(listenerId) })
</script>

传统 uni-app Vue2/Vue3 使用选项式生命周期，最小示例为：

<template><view><button @click="connect">连接 Play</button><text>{{ status }}</text></view></template>
<script>
import { connectBilling, onPurchasesUpdated, offPurchasesUpdated } from '@/uni_modules/lizhao-play-billing'
export default {
  data() { return { status: '尚未连接', listenerId: '' } },
  onLoad() {
    this.listenerId = onPurchasesUpdated(event => {
      this.status = '购买事件：' + event.purchases.length + ' 条，须按状态核验'
    })
  },
  onUnload() { offPurchasesUpdated(this.listenerId) },
  methods: {
    connect() {
      connectBilling({
        success: () => { this.status = '已连接' },
        fail: error => { this.status = error.errCode + ' · ' + error.errMsg },
        complete: result => { console.log('连接完成：' + result.requestId + '，ok=' + result.ok) }
      })
    }
  }
}
</script>

完整可交互页面见 uni_modules/lizhao-play-billing/example/uniappx/index.uvue 和 uni_modules/lizhao-play-billing/example/uniapp/index.vue。页面卸载移除自己的监听；只有应用级连接拥有者才调用 disconnectBilling，避免影响其它页面。

模块二：查询商品并购买用户选择的报价

以下 UTS 函数接受业务配置的真实商品 ID，以及查询返回、由用户明确选择的商品/报价。先展示 pricingPhases 中的币种、价格、周期和续期含义，再让用户确认。传统 JS 使用相同代码时去掉类型注解及类型 import 即可；完整 JS 页面已随插件提供。

import { queryProducts, launchPurchase, BillingProduct, BillingOffer } from '@/uni_modules/lizhao-play-billing'

export function loadProducts(productType: string, ids: string[], show: (products: BillingProduct[]) => void) {
  queryProducts({ productType: productType, productIds: ids,
    success: (result) => {
      show(result.products)
      console.log('商品数=' + result.products.length + '，未取回=' + result.unfetchedProducts.length)
    },
    fail: (error) => { console.error(error.errCode + ' · ' + error.errMsg) }
  })
}

export function buySelected(product: BillingProduct, offer: BillingOffer) {
  launchPurchase({ productType: product.productType, productId: product.productId, offerToken: offer.offerToken,
    success: (result) => { console.log('结算请求状态=' + result.status + '；等待独立购买事件') },
    fail: (error) => { console.error(error.errCode + ' · ' + error.errMsg) }
  })
}

不长期缓存 ProductDetails。若原报价失效，插件返回商品/报价错误，业务应刷新并重新让用户选择；不会自动换收费方案。试用也是报价的一部分，不能仅看第一阶段价格就声称永久免费。

模块三：恢复、核验与确认/消耗

import { restorePurchases, acknowledgePurchase, consumePurchase, BillingPurchase } from '@/uni_modules/lizhao-play-billing'

export function restoreCurrentPurchases(handle: (purchases: BillingPurchase[]) => void) {
  restorePurchases({
    success: (result) => {
      handle(result.purchases)
      for (const group of result.groups) {
        if (!group.ok && group.error != null) console.error(group.productType + '：' + group.error!.errCode)
      }
      console.log('部分结果=' + result.partial)
    },
    fail: (error) => { console.error(error.errCode + ' · ' + error.errMsg) }
  })
}

// 仅供已经完成可信后端核验和幂等发货的业务流程调用；函数本身不执行验单。
export function finalizeDeliveredPurchase(purchase: BillingPurchase, consumable: boolean) {
  if (purchase.purchaseState != 'purchased' || purchase.isSuspended) return
  if (consumable) {
    consumePurchase({ purchaseToken: purchase.purchaseToken,
      success: () => { console.log('消耗完成') },
      fail: (error) => { console.error(error.errCode + ' · outcomeUnknown=' + error.outcomeUnknown) }
    })
  } else if (!purchase.acknowledged) {
    acknowledgePurchase({ purchaseToken: purchase.purchaseToken,
      success: () => { console.log('确认完成') },
      fail: (error) => { console.error(error.errCode + ' · outcomeUnknown=' + error.outcomeUnknown) }
    })
  }
}

后端从已认证业务会话确定用户，核对配置包名、商品、Google 返回的购买状态及绑定标识；以购买 token 建唯一幂等记录，再按购买数量与权益合同入账。客户端传来的商品和“已验证”标记不能作为发货依据。Google 推荐把验单及敏感发货逻辑置于可信后端。购买安全建议

一次性商品可使用 purchases.productsv2.getproductpurchasev2，订阅使用 purchases.subscriptionsv2.get。两者由后端持有 Google 凭据访问；不把服务账号或 OAuth access token 放客户端。订阅结合 RTDN 和 Developer API 处理续费、取消、退款、到期和换档关联；autoRenewing=false 不等于权益已到期。

客户端确认/消耗超时可能已在 Google 执行，错误 outcomeUnknown=true 时先核对后端和当前购买状态，不重复发货。恢复不返回已经消耗的完整历史，历史权益从业务后端恢复。

模块四：订阅换档与辅助能力

import { launchPurchase, BillingProduct, BillingOffer, BillingPurchase } from '@/uni_modules/lizhao-play-billing'
export function replaceSubscription(product: BillingProduct, offer: BillingOffer, old: BillingPurchase, oldProductId: string) {
  launchPurchase({ productType: 'subs', productId: product.productId, offerToken: offer.offerToken,
    oldPurchaseToken: old.purchaseToken, oldProductId: oldProductId, replacementMode: 'deferred',
    success: () => { console.log('换档请求已受理；等待购买更新及服务端状态核对') },
    fail: (error) => { console.error(error.errCode + ' · ' + error.errMsg) }
  })
}

replacementMode 使用语义字符串，插件映射 Billing 9 的商品级常量；不要传旧 SDK 数字。实际支持模式还受旧计划、新计划、预付/自动续期规则和 Google 校验约束。openSubscriptionManagement 只是打开官方管理页面，不代表用户取消成功；showInAppMessages 的结果码不是“已显示广告”或已恢复权益。

API 用途速查

方法

除同步接口、监听注册/移除和诊断开关外，参数均为 options 对象，至少传 {}。完整强类型定义见 uni_modules/lizhao-play-billing/utssdk/interface.uts。

公共回调与时限

getBillingCapabilities/getBillingConfig/showInAppMessages 使用内部 15000ms 请求时限。launchPurchase 的时限只覆盖准备阶段，受理后没有“15秒内必须付款”的计时器。结果由独立购买事件取得。回调在公开函数返回请求 ID 后异步派发；客户回调异常不阻断 complete。

连接、查询和恢复参数

已有连接的配置不能静默更改；选项冲突返回错误，需显式断开后重连。getBillingStateSync 的 ready 是当时快照，不能保证下一次 SDK 调用成功。

购买及替换参数

换档三个旧参数必须一起提供，且仅适用 subs。KEEP_EXISTING、多商品、add-ons、替代结算和外部支付不在此版本合同内。同时只允许一个购买流程，未知结果时先恢复核对，不靠超时擅自重买。

其它参数

结果与事件

BillingResult 含 operation、requestId、elapsedMs、status、billingResponseCode、subResponseCode、debugMessage、state、partial，以及 products、unfetchedProducts、purchases、groups、capabilities、countryCode、messageResponseCode。不适用数组为空。原生和 uni-app x 的可空字段为 null；传统 uni-app 的原生到 JS 序列化可能省略 null 属性，接口因此将这些属性声明为可选，统一使用 value ?? null 读取。缺省/null 均表示不可得，不能推断成付款成功。

purchaseState 为 purchased/pending/unspecified。pending 不发货；purchased 仍需后端验证。购买事件无法证明对应某次请求时 requestId=null，不强行关联最近一次购买。SDK 可能重复回传同一购买，后端必须幂等；插件不会永久按 token 去重。

capabilities.feature 保留 SDK 原始特征字符串：subscriptions 为订阅、subscriptionsUpdate 为订阅替换、fff 为商品详情、bbb 为应用内消息、ggg 为结算配置、nnn 为包含暂停订阅。supported=false 时同时查看 billingResponseCode/debugMessage，不能将服务错误直接视为设备永远不支持。

错误码说明

errSubject 固定为 lizhao-play-billing。BillingFail 除标准 errCode/errMsg 外，还包括 operation、requestId、billingResponseCode、subResponseCode、debugMessage、retryable、outcomeUnknown、elapsedMs、nativeType、nativeCause、nativeStack。原始异常与 SDK 消息在桥接前脱敏；不可得原码为 null，未知原生信息有明确说明。

retryable 仅为技术提示，不授权重新购买。用户取消通常出现在独立购买事件内；launchPurchase 先前的 launched 回调不代表订单成功。结果未知不能解释成“未扣款”。

注意事项

平台、依赖和基座

实际付款仅适用于 Android 6.0/API23 及以上。uni-app Vue2/Vue3 与 uni-app x 提供同一 API 合同；iOS、Harmony、Web、微信/支付宝小程序仅保留明确不支持入口及诊断，不支持 Google Play 购买。nvue 未验收。不因某平台可导入就声明具备支付能力。

必须使用可用的 Google Play 环境、匹配包名、已配置商品、符合资格的账号及匹配原生基座。APK 安装来源和许可测试规则以 Google 测试说明 为准；许可测试账号与普通内部测试账号不同，后者可能产生真实扣款。不要把模拟成功当作验收。

修改原生 UTS/Kotlin、SDK、Manifest 或配置后重新原生联编/重打 Android 自定义基座；WGT 不能更新已编进基座的原生代码。本插件声明 BILLING 并查询 Play Store；当前独立 APK 的真实合并依赖还包含 INTERNET、ACCESS_NETWORK_STATE 和应用自身签名级 DYNAMIC_RECEIVER_NOT_EXPORTED_PERMISSION。完整宿主还可能引入其它权限，SDK 数据处理和商店数据安全声明应依据实际构建产物及应用业务填写。

生命周期、权益与隐私

前台恢复只查询购买，不自动付款。断开连接不取消 Google 订单、不撤销用户权益。订阅暂停、退款、取消与到期不应仅凭客户端某一布尔值判断。确认/消耗应由后端流程统筹，客户端与后端不要争抢同一交易终态。

purchaseToken、oldPurchaseToken、offerToken、原始购买 JSON、签名、完整订单号和账号标识不得写到 console、监控或剪贴板。示例仅在业务内存持有凭据，卸载清理页面引用；不默认保存原始凭据或上传诊断。账号混淆标识不要直接用邮箱/电话。

诊断与验收范围

示例页面底部的一键复制包含运行时白名单环境、getBillingStateSync、getDiagnosticsSync 和全部已保留操作日志。报告标注编号、UTC时间、时区、条数和正文长度，分段来自固定快照；只有实际剪贴板 success 才推进分段，失败保留同段并提供可选择文本。复制不清日志。

插件与报告采用有界日志，错误另行保留，淘汰计数可见。构建身份由本插件 package 与源码生成；它不是客户安装 APK 的 HX/基座版本。未注入或无法可靠采集的 HX、编译器、基座及设备字段明确写 unknown，运行时版本另标来源。报告辅助源码为 uni_modules/lizhao-play-billing/example/report.uts，传统宿主对应生成物为 uni_modules/lizhao-play-billing/static/report.js。

发布前还需在有 Play 测试环境的真实宿主上覆盖购买成功/取消、PENDING 后完成、断网、重启补单、订阅替换、确认/消耗、部分恢复，以及手机系统剪贴板分段与失败回退。当前文档不把本地静态/资源/原生测试描述为这些场景均已通过。

作者系列 UTS 插件

以下为作者已发布的 UTS 插件，可按能力方向查找。