rc-configuring-the-sdk

Configuring the RevenueCat Android SDK

Use this skill to add and configure RevenueCat (purchases-kt) in an Android app. A single Purchases.configure call replaces BillingClient setup, connection lifecycle management, reconnection handling, and launch-time purchase queries.

Work through the phases in order. The full chapter on revenuecat.com has the complete reference text.

Phase 1: Discovery

Find out whether RevenueCat is already wired up and where billing code currently lives.

1. Search for an existing configure call and prior SDK version.

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

2. Search for the existing billing surface you may be replacing.

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

3. Record answers before moving on.

If Purchases.configure already runs, stop and confirm with the user before changing it. Configuration runs once per process.

Phase 2: Plan

Decide three things before writing code.

2.1 Where to call configure

Call configure exactly once per process. Calling it from an Activity risks re-running it on configuration changes if you are not careful; the Application path avoids that.

2.2 App user id strategy

Do not pass device ids, email addresses, or values that can change. If you do not have the id at startup, configure anonymously and call logIn after authentication.

2.3 Log level

Switch on BuildConfig.DEBUG so production builds stay quiet.

Phase 3: Execute

3.1 Add the Gradle dependency

In the app module build.gradle.kts:

dependencies {
    implementation("com.revenuecat.purchases:purchases:<latest>")
}

Replace <latest> with the current published version. If the project uses a Groovy build.gradle, use implementation 'com.revenuecat.purchases:purchases:<latest>'. Sync Gradle after the change.

3.2 Call configure at startup

In your Application subclass:

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()
        )
    }
}

Register the class in AndroidManifest.xml with android:name=".App" on <application>. Keep the public Android SDK key out of source; inject it through BuildConfig or a secret manager.

3.3 Confirm the wiring with a minimal offerings fetch

From any coroutine scope after configure has run:

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

A non-null offerings.current identifier means the API key, package name, and network path are working. If you see null, check the dashboard offering setup and the package name match before touching code.

What the SDK handles for you

Once configured, you do not need to:

• Create or close a BillingClient
• Call startConnection or endConnection
• Check isReady or write reconnection logic for SERVICE_DISCONNECTED
• Call queryPurchasesAsync at launch; the SDK posts unfinished transactions automatically

Common pitfalls

References

• Full chapter