rc-configuring-the-sdk

配置 RevenueCat Android SDK

使用此技能在 Android 应用中添加并配置 RevenueCat（purchases-kt）。一次 Purchases.configure 调用即可替代 BillingClient 设置、连接生命周期管理、重新连接处理和启动时的购买查询。

请按顺序完成各阶段。revenuecat.com 上的完整章节提供了完整参考内容。

阶段 1：发现

确认是否已接入 RevenueCat，以及当前的计费代码位于何处。

1. 搜索已有的 configure 调用和之前使用的 SDK 版本。

   rg -n "Purchases\.configure|PurchasesConfiguration" --type kotlin --type java
   rg -n "com\.revenuecat\.purchases" -g '*.gradle*' -g '*.toml'
   

2. 搜索可能需要替换的现有计费部分。

   rg -n "BillingClient|PurchasesUpdatedListener|startConnection" --type kotlin --type java
   

3. 记录答案后再继续。

问题	查找位置
是否已调用 Purchases.configure？	应用启动代码、Application.onCreate、主 Activity.onCreate
当前由哪个模块负责计费？	app/build.gradle(.kts)、任何 :billing 模块
是否有包含稳定用户 ID 的身份验证系统？	登录流程、会话存储
是否可检测调试版与发布版构建？	BuildConfig.DEBUG

如果已调用 Purchases.configure，请先停止操作，并在更改前向用户确认。每个进程只运行一次配置。

阶段 2：规划

编写代码前，先决定以下三件事。

2.1 在何处调用 configure

位置	选择时机
Application.onCreate	默认选择。确保任何 Activity 或后台工作访问购买功能前，SDK 已准备就绪。
首个 Activity.onCreate	仅当应用没有自定义 Application 类，且你不愿意添加一个时选择。

每个进程只调用一次 configure。如果不慎在 Activity 中调用，配置更改时可能会重复运行；使用 Application 可避免这种情况。

2.2 应用用户 ID 策略

策略	传给 appUserID 的值	适用情况
匿名	null	用户可以在登录前购买，或应用没有身份验证。之后调用 Purchases.sharedInstance.logIn(id) 合并历史记录。
已知用户	稳定的后端 ID（例如 "user_12345"）	用户在购买前始终需要通过身份验证。

不要传入设备 ID、电子邮件地址或可能发生变化的值。如果应用启动时没有 ID，请先匿名配置，并在身份验证后调用 logIn。

2.3 日志级别

构建类型	日志级别
调试版	集成期间使用 LogLevel.DEBUG 或 VERBOSE
发布版	LogLevel.INFO（默认）或 WARN

根据 BuildConfig.DEBUG 切换日志级别，以确保生产构建保持安静。

阶段 3：执行

3.1 添加 Gradle 依赖项

在应用模块的 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 密钥放在源代码中；请通过 BuildConfig 或密钥管理器注入。

3.3 通过最简 offerings 获取操作确认接线正确

在 configure 运行后，从任意协程作用域中执行：

lifecycleScope.launch {
    val offerings = Purchases.sharedInstance.awaitOfferings()
    Log.d("RC", "current=${offerings.current?.identifier}")
}

非空的 offerings.current 标识符表示 API 密钥、包名和网络路径均正常。如果看到 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 标记为当前项。
出现重复的匿名用户	每个进程中多次调用 configure，或传入 appUserID 的 ID 不稳定。
生产环境中日志过于详细	日志级别未根据 BuildConfig.DEBUG 设置。

参考资料

• 完整章节