revenuecat/ai-toolkit

rc-configuring-the-sdk

Use this skill when adding and configuring the RevenueCat Android SDK (purchases-android, artifact com.revenuecat.purchases:purchases) in an app.

Ver código-fonte

Como usar

  1. Copie o comando e verifique o pacote antes de instalar no seu ambiente de agente.
  2. Consulte no original as ferramentas, credenciais e ambientes necessários.
  3. Descreva os dados de entrada e a entrega esperada; confira a saída com as fontes.
npx skills add https://github.com/revenuecat/ai-toolkit --skill rc-configuring-the-sdk

Antes de começar

  • A instalação não inclui assinatura de modelo, franquia API ou acesso aos seus arquivos.
  • Estrelas e instalações indicam atividade, não um teste independente de qualidade ou segurança.
Documento original do Skill

Renderizado do repositório de origem, preservando títulos, exemplos, código, tabelas, links e imagens.

Configuring the RevenueCat Android SDK

Use this skill to add and configure RevenueCat (com.revenuecat.purchases:purchases) 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.
bash
   rg -n "Purchases\.configure|PurchasesConfiguration" --type kotlin --type java
   rg -n "com\.revenuecat\.purchases" -g '*.gradle*' -g '*.toml'
  1. Search for the existing billing surface you may be replacing.
bash
   rg -n "BillingClient|PurchasesUpdatedListener|startConnection" --type kotlin --type java
  1. Record answers before moving on.
QuestionWhere 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.

Phase 2: Plan

Decide three things before writing code.

2.1 Where to call configure

LocationWhen to choose
Application.onCreateDefault. Ensures the SDK is ready before any Activity or background work touches purchases.
First Activity.onCreateOnly 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.

2.2 App user id strategy

StrategyPass to appUserIDUse when
AnonymousnullUsers can purchase before signing in, or you have no auth. Later call Purchases.sharedInstance.logIn(id) to merge history.
Known userYour 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.

2.3 Log level

BuildLog level
DebugLogLevel.DEBUG or VERBOSE while integrating
ReleaseLogLevel.INFO (default) or WARN

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:

kotlin
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.

Use 11.3.0 or newer (latest as of 2026-11-16). Earlier 11.x releases can leave calls such as getOfferings() hanging when the Play Billing connection stalls; 11.3.0 fails them with StoreProblemError after 10 seconds instead (an app held on 10.x gets the same fix in 10.30.3). It requires minSdk 23, compileSdk 35 or higher in the app and in every module that depends on it, and Kotlin 2.1.0 or newer. Below those, the build fails at checkDebugAarMetadata (androidx.core 1.15.0 requires compileSdk 35) or with "Module was compiled with an incompatible version of Kotlin". It exposes Play Billing Library 9.1.0 as an api dependency, so 9.1.0 is on the app's compile classpath. A Billing dependency the app declares itself must be 9.0.0 or later, and billing-ktx 9.x needs Kotlin 2.2 or newer. App code that still uses SkuDetails, SkuDetailsParams, SkuDetailsResponseListener, BillingClient.SkuType, QueryPurchaseHistoryParams, or BillingFlowParams.Builder.setSkuDetails stops compiling; move it to ProductDetails and apply the other Billing 9 changes first (see google-play/pbl-v8-to-v9-migration).

If Phase 1 finds an existing purchases dependency on 8.x or older (Play Billing Library 7 or older), upgrade it: Play stopped accepting app updates built on Play Billing Library 7 after August 31, 2026 (November 1, 2026 with an extension). 9.x and 10.x use Play Billing Library 8, which Play accepts in new apps and updates until August 31, 2027 (November 1, 2027 with an extension). Moving from 10.x to 11.x leaves the RevenueCat API unchanged, but it is more than a version bump. Besides the build floors above, a Play Store the system blocks (for example an OEM kids mode) now fails with PurchaseNotAllowedError instead of StoreProblemError (see error-handling), and RevenueCatUI applies Compose BOM 2026.06.01 as a platform constraint, which raises the app's own Compose libraries. Move purchases-ui to the same version as purchases (com.revenuecat.purchases:purchases-bom pins them together), and read the v11 migration guide for the full list.

The sample below reads the API key from BuildConfig.RC_API_KEY. AGP 8+ does not generate BuildConfig by default, so declare the field explicitly in the same build.gradle.kts, reading the key from a Gradle property (for example RC_API_KEY=goog_... in ~/.gradle/gradle.properties or a CI secret) so it never lands in source:

kotlin
android {
    buildFeatures {
        buildConfig = true
    }
    defaultConfig {
        buildConfigField("String", "RC_API_KEY", "\"${providers.gradleProperty("RC_API_KEY").get()}\"")
    }
}

3.2 Call configure at startup

In your Application subclass:

kotlin
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.

Check the android:launchMode of the Activity that triggers purchases. It must be standard (the default) or singleTop. Any other launch mode lets backgrounding the app (for example, to verify payment in a banking app) cancel the purchase.

3.3 Confirm the wiring with a minimal offerings fetch

From any coroutine scope after configure has run:

kotlin
lifecycleScope.launch {
    try {
        val offerings = Purchases.sharedInstance.awaitOfferings()
        Log.d("RC", "current=${offerings.current?.identifier}")
    } catch (e: PurchasesException) {
        Log.e("RC", "${e.error.code}: ${e.error.message}")
    }
}

awaitOfferings() throws PurchasesException when it cannot resolve any offering: ConfigurationError means the dashboard has no products configured, or none of them can be fetched from Play (product IDs, package name, product not active, app not published on a closed track, test account not a license tester, wrong platform API key), and InvalidCredentialsError means the API key is wrong. A null offerings.current with no exception means either no Default offering is set, or none of the Default offering's products could be fetched from Play while another offering's could (check that offering's product IDs and status).

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

SymptomLikely cause
kotlin.UninitializedPropertyAccessException: There is no singleton instanceCode touched Purchases.sharedInstance before configure ran. Move configure to Application.onCreate, or guard with Purchases.isConfigured.
awaitOfferings() throws ConfigurationErrorProducts are missing in the dashboard, or none can be fetched from Play (product IDs, package name, product not active, app not on a closed track, tester not licensed, wrong platform API key).
awaitOfferings() throws InvalidCredentialsErrorWrong API key.
offerings.current is null, no exception thrownNo Default offering set, or the Default offering's products cannot be fetched from Play.
Duplicate anonymous usersApp reinstalled or data cleared, or logOut() called, before the user logged in. Call logIn with a stable id after authentication. An unstable appUserID creates duplicate identified users.
Verbose logs in productionLog level not gated on BuildConfig.DEBUG.

References

do mesmo repositório

Mais Skills

Todos os Skills
revenuecat
Comunidade

create-revenuecat-project

Set up a complete RevenueCat project from scratch — creates apps, products, entitlements, offerings, and packages in the correct order. Use when the user wants to create a new RevenueCat project, configure in-app purchases, set up subscriptions or monetization, or bootstrap IAP infrastructure for iOS, Android, or Web.

Instalações / 1h
2
GitHub Stars
79
Atualizado
17 de nov.
revenuecat
Comunidade

rc-cancellations-pauses-winback

Use this skill when surfacing cancellation, pause, and winback state on Android with RevenueCat. Covers reading unsubscribeDetectedAt, billingIssueDetectedAt, pause state and resume date via SubscriptionInfo.autoResumeDate, showManageSubscriptions for the deep link, and the SUBSCRIPTIONPAUSED webhook.

Instalações / 1h
2
GitHub Stars
79
Atualizado
17 de nov.
revenuecat
Comunidade

rc-plan-changes

Use this skill when implementing subscription upgrades, downgrades, and plan switches via RevenueCat on Android. Covers StoreReplacementMode, picking a replacement mode, and letting the SDK manage linkedPurchaseToken chaining.

Instalações / 1h
2
GitHub Stars
79
Atualizado
17 de nov.
revenuecat
Comunidade

rc-purchase-flow

Use this skill when implementing a RevenueCat purchase on Android. Covers awaitPurchase, PurchasesTransactionException, reading CustomerInfo entitlements to grant access, restoring purchases, and the six SDK managed steps that happen inside a single call.

Instalações / 1h
2
GitHub Stars
79
Atualizado
17 de nov.