更新记录

1.0.0（2026-09-30）

• 初始版本，实现iOS、安卓双端

平台兼容性

uni-app(5.25)

uni-app x(5.25)

其他

hxr-revenue-cat

适用于 uni-app 和 uni-app x 的 RevenueCat UTS 插件。通过 Android、iOS 原生 SDK 提供统一的内购、订阅、原生付费墙和 Customer Center 接口。

本插件是独立开发的集成方案，与 RevenueCat, Inc. 无隶属或官方背书关系。

环境要求

• Android 7.0（API 24）或更新版本
• iOS 15.0 或更新版本
• RevenueCat Android SDK / RevenueCatUI 10.23.3
• RevenueCat iOS SDK / RevenueCatUI 5.91.0
• 已在 RevenueCat 中配置与 App Store Connect、Google Play 对应的商品

插件包含原生 SDK 依赖，需要制作自定义基座或使用云打包；标准基座不包含 RevenueCat。

商店配置

iOS

1. BundleID必须和AppStore一致，不然不行
2. 在 App Store Connect 创建商品，并导入 RevenueCat。
3. 使用以 appl_ 开头的 RevenueCat iOS 公共 SDK Key。
4. 如果用test_开头，那就完全是和RevenueCat交互，纯走流程，不会和Apple交互，可以用来测试基本的流程。

Android

1. 至少将应用发布到 Google Play 内部测试轨道。
2. 在 Play Console 创建商品或订阅，并导入 RevenueCat。
3. 在 RevenueCat 中关联 Google Play 服务账号。
4. 使用以 goog_ 开头的 RevenueCat Android 公共 SDK Key。

初始化

在用户同意隐私政策后调用一次 configure()。可以传入与你的后端一致的用户 ID；不传 appUserId 时，RevenueCat 会创建匿名用户。

import {
  configure,
  onCustomerInfoUpdated,
} from '@/uni_modules/hxr-revenue-cat'

await configure({
  apiKey: uni.getSystemInfoSync().platform == 'ios'
    ? 'appl_your_public_sdk_key'
    : 'goog_your_public_sdk_key',
  appUserId: null,
  logLevel: 'debug',
})

onCustomerInfoUpdated((customerInfo) => {
  console.log('RevenueCat 用户信息更新', customerInfo)
})

正式发布时请关闭 debug 或 verbose 级别的日志。

商品与购买

import {
  getOfferings,
  purchasePackage,
  restorePurchases,
  isEntitlementActive,
} from '@/uni_modules/hxr-revenue-cat'

const offerings = await getOfferings()

// Package ID 通常为 $rc_monthly、$rc_annual，也可以是自定义 ID。
const purchase = await purchasePackage('$rc_monthly')

const restoredCustomer = await restorePurchases()
const hasPro = await isEntitlementActive('pro')

若 Package 不属于当前 Offering，可在第二个参数传入 Offering ID：

await purchasePackage('$rc_annual', 'default')

App Store 推广商品购买（仅 iOS）

用户从 App Store 点击推广内购商品进入 App 时，使用 onPromotedPurchaseResult 接收该笔购买的结果。应在 configure() 前注册监听；页面级监听在离开页面时移除。demo 的 pages/index/revenuecat.uvue 有完整示例。

import {
  configure,
  onPromotedPurchaseResult,
  offPromotedPurchaseResult,
  isEntitlementActive,
} from '@/uni_modules/hxr-revenue-cat'

const listenerId = onPromotedPurchaseResult((result) => {
  if (result.status == 'purchased') {
    isEntitlementActive('pro').then((active) => {
      console.log(result.productIdentifier, active, result.customerInfo)
    })
  } else if (result.status == 'failed') {
    console.error(result.productIdentifier, result.error)
  }
  // cancelled 不解锁权益。
})

await configure({ apiKey: 'appl_your_public_sdk_key' })

// 不再需要监听时调用 offPromotedPurchaseResult(listenerId)。

事件包含 status（purchased、cancelled、failed）、productIdentifier 和可能为 null 的 transactionIdentifier。成功时附带 customerInfo，失败时附带 error。普通 purchasePackage() 不触发此事件；Android 上此监听无事件。是否解锁仍以 RevenueCat Entitlement 为准。

用户身份

import { logIn, logOut, getCustomerInfo, syncPurchases } from '@/uni_modules/hxr-revenue-cat'

await logIn('your-backend-user-id')
const customerInfo = await getCustomerInfo()

// 仅在迁移购买记录，或同步 SDK 外完成的购买时调用。
await syncPurchases()

// 切换回 RevenueCat 匿名用户。
await logOut()

原生付费墙

如果你不是自己实现付费墙，你可以在 RevenueCat 后台随便拖一拖，改一改就能配置出付费墙，然后用插件api就能直接唤起付费墙，同时购买、恢复购买等等逻辑都不需要你处理，你只需关心返回的状态是否激活会员，刷新你的界面就行。 先在 RevenueCat 控制台为目标 Offering 配置 Paywall。

import { presentPaywall, presentPaywallIfNeeded } from '@/uni_modules/hxr-revenue-cat'

const result = await presentPaywall({
  offeringIdentifier: 'default',
  displayCloseButton: true,
})

// 用户已拥有 pro 权益时返回 { status: 'not_presented' }。
const conditionalResult = await presentPaywallIfNeeded({
  entitlementIdentifier: 'pro',
  offeringIdentifier: 'default',
  displayCloseButton: true,
})

返回的 status 可能是 purchased、restored、cancelled 或 not_presented。SDK 错误会使 Promise 拒绝；错误消息是包含 code、message 和 userCancelled 的 JSON 字符串。

Customer Center

使用前需在 RevenueCat 控制台配置 Customer Center。

import { presentCustomerCenter } from '@/uni_modules/hxr-revenue-cat'

const result = await presentCustomerCenter()
// { status: 'dismissed' }

返回数据

日期字段使用毫秒级 Unix 时间戳。用户信息包括：

• originalAppUserId
• isAnonymous
• activeSubscriptions
• allPurchasedProductIdentifiers
• activeEntitlements 和 allEntitlements
• originalPurchaseDate 和 latestExpirationDate
• managementURL

getOfferings() 返回的数据中，all 对象按 Offering ID 索引。每个 Offering 包含 availablePackages；Package 中包含统一格式的商品、价格、货币和订阅周期字段。

错误处理

try {
  await purchasePackage('$rc_monthly')
} catch (error) {
  // 原生错误以 JSON 字符串放在 Error.message 中。
  const details = JSON.parse((error as Error).message)
  if (!details.userCancelled) {
    console.error(details.code, details.message)
  }
}

隐私说明

iOS商店隐私申报可以直接写未收集任何数据