在 Android 应用中接入并配置 RevenueCat…

当需要在 Android 应用中添加并配置 RevenueCat（purchases-kt）SDK 时，按阶段完成发现、规划与执行。

适用场景

解决思路

1. Phase 1 发现：用 rg -n "Purchases\.configure|PurchasesConfiguration" --type kotlin --type java 和 rg -n "com\.revenuecat\.purchases" -g '*.gradle*' -g '*.toml' 搜索是否已有 configure 调用及旧版本 SDK。
2. Phase 1 发现：用 rg -n "BillingClient|PurchasesUpdatedListener|startConnection" --type kotlin --type java 搜索可能被替换的现有计费代码。
3. Phase 1 发现：在继续前记录以下问题的答案——Purchases.configure 是否已被调用（查看 App 启动、Application.onCreate、主 Activity.onCreate）；当前哪个模块负责计费（app/build.gradle(.kts)、任何 :billing 模块）；是否有带稳定用户 id 的认证系统（登录流程、会话存储）；是否可检测 debug 与 release 构建（BuildConfig.DEBUG）。
4. Phase 1 发现：如果 Purchases.configure 已在运行，先停下并与用户确认再修改；配置每个进程只运行一次。
5. Phase 2 规划：决定 configure 的调用位置——默认放在 Application.onCreate，确保 SDK 在任何 Activity 或后台任务接触购买前就绪；仅当应用没有自定义 Application 类且不愿添加时，才放在首个 Activity.onCreate。
6. Phase 2 规划：每个进程只调用一次 configure；从 Activity 调用可能在配置变更时重复执行，Application 路径可避免此问题。
7. Phase 2 规划：决定 app user id 策略——匿名时向 appUserID 传 null（用户可在登录前购买或没有认证），之后调用 Purchases.sharedInstance.logIn(id) 合并历史；已知用户时传稳定的后端 id（例如 "user_12345"），适用于用户购买前总是已认证。
8. Phase 2 规划：不要传设备 id、邮箱地址或会变化的值；如果启动时没有该 id，先匿名配置，认证后再调用 logIn。
9. Phase 2 规划：决定日志级别——Debug 构建用 LogLevel.DEBUG，集成期间可用 VERBOSE；Release 构建用 LogLevel.INFO（默认）或 WARN；用 BuildConfig.DEBUG 切换，使生产构建保持安静。
10. Phase 3 执行：在 app 模块 build.gradle.kts 中添加依赖 implementation("com.revenuecat.purchases:purchases:<latest>")，将 <latest> 替换为当前发布版本；若项目使用 Groovy build.gradle，则用 implementation 'com.revenuecat.purchases:purchases:<latest>'；修改后同步 Gradle。
11. Phase 3 执行：在 Application 子类的 onCreate 中设置 Purchases.logLevel = if (BuildConfig.DEBUG) LogLevel.DEBUG else LogLevel.INFO，并调用 Purchases.configure(PurchasesConfiguration.Builder(this, BuildConfig.RC_API_KEY).appUserID(null).build())，其中 appUserID 可换成稳定用户 id。
12. Phase 3 执行：在 AndroidManifest.xml 的 <application> 上用 android:name=".App" 注册该类；不要把公开的 Android SDK key 放进源码，通过 BuildConfig 或密钥管理器注入。
13. Phase 3 执行：在 configure 运行后，从任意协程作用域用 lifecycleScope.launch { val offerings = Purchases.sharedInstance.awaitOfferings(); Log.d("RC", "current=${offerings.current?.identifier}") } 做最小 offerings 拉取验证；若 offerings.current 标识非 null，说明 API key、包名和网络路径正常；若为 null，先检查仪表盘 offering 设置和包名匹配，再改代码。
14. 配置完成后无需：创建或关闭 BillingClient；调用 startConnection 或 endConnection；检查 isReady 或为 SERVICE_DISCONNECTED 编写重连逻辑；在启动时调用 queryPurchasesAsync（SDK 会自动上报未完成交易）。
15. 常见陷阱：出现 IllegalStateException: There is no singleton instance，说明在 configure 运行前访问了 Purchases.sharedInstance，应把 configure 移到 Application.onCreate。
16. 常见陷阱：Offerings 始终为 null，可能是 Play Console 与仪表盘之间的包名不匹配，或 offering 未标记为 current。
17. 常见陷阱：出现重复匿名用户，可能是每个进程多次调用 configure，或传入了不稳定的 id 作为 appUserID。
18. 常见陷阱：生产环境出现详细日志，说明日志级别未用 BuildConfig.DEBUG 控制。

适用边界 · 注意事项

• 如果 Purchases.configure 已在运行，不要直接修改，应先与用户确认；配置每个进程只运行一次。
• 不要从 Activity 调用 configure，除非应用没有自定义 Application 类且不愿添加，否则可能在配置变更时重复执行。
• 不要传设备 id、邮箱地址或会变化的值作为 appUserID。