Terminal
Terminal/Skill
Walks through adding the RevenueCat Android SDK to an app: Gradle dependency, Purchases.configure, the app user ID and log level.
By RevenueCat
Works with
npx skills add revenuecat/ai-toolkit --skill rc-configuring-the-sdkUse 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.
Find out whether RevenueCat is already wired up and where billing code currently lives.
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'
Search for the existing billing surface you may be replacing.
rg -n "BillingClient|PurchasesUpdatedListener|startConnection" --type kotlin --type java
Record answers before moving on.
| Question | Where to look |
|---|---|
Is Purchases.configure already called? | App startup, Application.onCreate, main Activity.onCreate |
| Which module owns billing today? | app/build.gradle(.kts), any :billing module |
| Is there an auth system with a stable user id? | Login flow, session store |
| Debug vs release build detection available? | BuildConfig.DEBUG |
If Purchases.configure already runs, stop and confirm with the user before changing it. Configuration runs once per process.
Decide three things before writing code.
| Location | When to choose |
|---|---|
Application.onCreate | Default. Ensures the SDK is ready before any Activity or background work touches purchases. |
First Activity.onCreate | Only if the app has no custom Application class and you are not willing to add one. |
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.
| Strategy | Pass to appUserID | Use when |
|---|---|---|
| Anonymous | null | Users can purchase before signing in, or you have no auth. Later call Purchases.sharedInstance.logIn(id) to merge history. |
| Known user | Your stable backend id (for example "user_12345") | Users are always authenticated before purchase. |
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.
| Build | Log level |
|---|---|
| Debug | LogLevel.DEBUG or VERBOSE while integrating |
| Release | LogLevel.INFO (default) or WARN |
Switch on BuildConfig.DEBUG so production builds stay quiet.
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.
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.
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.
Once configured, you do not need to:
BillingClientstartConnection or endConnectionisReady or write reconnection logic for SERVICE_DISCONNECTEDqueryPurchasesAsync at launch; the SDK posts unfinished transactions automatically| Symptom | Likely cause |
|---|---|
IllegalStateException: There is no singleton instance | Code touched Purchases.sharedInstance before configure ran. Move configure to Application.onCreate. |
Offerings always null | Package name mismatch between Play Console and dashboard, or offering not marked current. |
| Duplicate anonymous users | configure called more than once per process, or an unstable id passed as appUserID. |
| Verbose logs in production | Log level not gated on BuildConfig.DEBUG. |