配置 RevenueCat Android SDK
用途
该技能用于在 Android 应用中添加并配置 RevenueCat（purchases-kt）。一次 Purchases.configure 调用即可替代 BillingClient 的设置、连接生命周期管理、重连处理以及启动时的购买查询。需按阶段顺序执行，完整章节位于 revenuecat.com。
技能按三个阶段的流程展开。
第一阶段：发现
先确认 RevenueCat 是否已接入，以及当前计费代码所在位置。
查找已有的 configure 调用和此前的 SDK 版本：
rg -n "Purchases.configure|PurchasesConfiguration" --type kotlin --type java rg -n "com.revenuecat.purchases" -g '.gradle' -g '*.toml'
查找可能被替换的现有计费接口：
rg -n "BillingClient|PurchasesUpdatedListener|startConnection" --type kotlin --type java
在继续前记录以下问题：Purchases.configure 是否已被调用（查看应用启动、Application.onCreate、主 Activity.onCreate）；当前哪个模块负责计费（app/build.gradle(.kts)、任何 :billing 模块）；是否存在带稳定用户 id 的认证系统（登录流程、会话存储）；是否可检测 debug 与 release 构建（BuildConfig.DEBUG）。
如果 Purchases.configure 已在运行，应停止并在修改前与用户确认。配置在每个进程中只运行一次。
第二阶段：规划
写代码前先确定三件事。
2.1 在哪里调用 configure
Application.onCreate：默认选择，确保 SDK 在任何 Activity 或后台工作触及购买之前就绪。
首个 Activity.onCreate：仅当应用没有自定义 Application 类且不愿意添加时使用。
configure 每个进程只能调用一次。从 Activity 调用可能因配置变更而重复执行；Application 路径可避免这一点。
2.2 App 用户 id 策略
匿名：向 appUserID 传 null。适用于用户可在登录前购买或没有认证的情况。之后调用 Purchases.sharedInstance.logIn(id) 合并历史。
已知用户：传入稳定的后端 id（例如 "user_12345"）。适用于用户始终在购买前完成认证的情况。
不要传设备 id、邮箱或会变化的值。如果启动时没有该 id，先匿名配置，认证后再调用 logIn。
2.3 日志级别
Debug 构建使用 LogLevel.DEBUG 或 VERBOSE（集成期间）；Release 构建使用 LogLevel.INFO（默认）或 WARN。通过 BuildConfig.DEBUG 切换，让生产构建保持安静。
第三阶段：执行
3.1 添加 Gradle 依赖
在 app 模块的 build.gradle.kts 中：
dependencies { implementation("com.revenuecat.purchases:purchases:<latest>") }
将 <latest> 替换为当前发布版本。如果项目使用 Groovy build.gradle，则用 implementation 'com.revenuecat.purchases:purchases:<latest>'。修改后同步 Gradle。
3.2 在启动时调用 configure
在 Application 子类中：
class App : Application() { override fun onCreate() { super.onCreate() Purchases.logLevel = if (BuildConfig.DEBUG) LogLevel.DEBUG else LogLevel.INFO Purchases.configure( PurchasesConfiguration.Builder(this, BuildConfig.RC_API_KEY) .appUserID(null) // or your stable user id .build() ) } }
在 AndroidManifest.xml 的 <application> 上以 android:name=".App" 注册该��。不要把公开的 Android SDK key 写进源码；通过 BuildConfig 或密钥管理器注入。
3.3 用最小 offerings 拉取确认接线
在 configure 运行后，从任意协程作用域：
lifecycleScope.launch { val offerings = Purchases.sharedInstance.awaitOfferings() Log.d("RC", "current=${offerings.current?.identifier}") }
offerings.current 的 identifier 非空，说明 API key、包名和网络路径正常。如果为 null，先检查仪表盘的 offering 设置和包名是否匹配，再动代码。
SDK 替你处理的事项
配置完成后，你无需：创建或关闭 BillingClient；调用 startConnection 或 endConnection；检查 isReady 或为 SERVICE_DISCONNECTED 编写重连逻辑；在启动时调用 queryPurchasesAsync；SDK 会自动上传未完成的交易。
常见陷阱
症状：IllegalStateException: There is no singleton instance。可能原因：代码在 configure 运行前访问了 Purchases.sharedInstance。应将 configure 移到 Application.onCreate。
症状：Offerings 始终为 null。可能原因：Play Console 与仪表盘的包名不匹配，或 offering 未标记为 current。
症状：出现重复匿名用户。可能原因：configure 每个进程被调用多次，或传入的 appUserID 不稳定。
症状：生产环境出现详细日志。可能原因：日志级别没有用 BuildConfig.DEBUG 控制。
限制
资料中除上述内容外，未提供更多功能、收费、价格、平台或效果信息。