Chapter 5: Configuring the SDK

Integrating the Play Billing Library directly means setting up BillingClient, managing the connection lifecycle, handling SERVICE_DISCONNECTED errors, implementing reconnection logic, setting up the PurchasesUpdatedListener, querying products, and querying existing purchases on launch.

With RevenueCat, all of that is replaced by a single configure() call. This chapter covers the configuration options and what the SDK does automatically.

The configure() Call

Purchases.configure(
    PurchasesConfiguration.Builder(context, apiKey)
        .appUserID(userId)
        .build()
)

That is the minimum required setup. The SDK:

• Creates and manages a BillingClient instance internally
• Handles all connection lifecycle events
• Reconnects automatically on SERVICE_DISCONNECTED
• Queries existing purchases on connection
• Posts unfinished transactions to the RevenueCat backend

You do not call startConnection(), endConnection(), or check isReady. You do not write a reconnection handler.

appUserID

Pass your own user ID if you have an authentication system:

.appUserID("user_12345")

Pass null to let RevenueCat generate an anonymous ID. Anonymous users can be identified later with Purchases.sharedInstance.logIn("user_12345"), RevenueCat will merge the anonymous purchase history with the identified user.

If your users are always authenticated before they can purchase, pass the ID at configure time. If anonymous purchases are possible, pass null and call logIn() after authentication.

showInAppMessagesAutomatically

Defaults to true. When enabled, the SDK automatically calls showInAppMessages() when the BillingClient connects, which displays Google Play's in-app messaging for payment recovery (grace period and account hold prompts). This covers most of what Chapter 12 in the raw billing handbook describes.

To handle it manually:

.showInAppMessagesAutomatically(false)
// Then call when you want to show it:
Purchases.sharedInstance.showInAppMessagesIfNeeded(
    activity,
    inAppMessageTypes = listOf(InAppMessageType.BILLING_ISSUES) // default; customize as needed
)

purchasesAreCompletedBy

Defaults to PurchasesAreCompletedBy.REVENUECAT. In this mode, RevenueCat finishes (acknowledges or consumes) every purchase automatically.

Set to PurchasesAreCompletedBy.MY_APP if you have an existing billing implementation and want to use only RevenueCat's backend for analytics and entitlement tracking without changing your purchase flow. In this mode, you are responsible for acknowledging purchases within 3 days, RevenueCat will not do it for you.

entitlementVerificationMode

Defaults to EntitlementVerificationMode.DISABLED. Setting it to INFORMATIONAL enables response signature verification: the SDK verifies that CustomerInfo responses from the RevenueCat backend were not tampered with in transit.

.entitlementVerificationMode(EntitlementVerificationMode.INFORMATIONAL)

In INFORMATIONAL mode, verification failures are logged but do not block access. Set to ENFORCED to block access on verification failure (more secure, but can affect users if there are network issues).

diagnosticsEnabled

Defaults to false. When enabled, the SDK sends performance and error metrics to RevenueCat. No personal data is collected. Useful for troubleshooting production issues with RevenueCat support.

.diagnosticsEnabled(true)

Querying Existing Purchases

You do not call queryPurchasesAsync() at launch. The SDK does this automatically when the BillingClient connection is established. Any purchases that were not yet posted to the RevenueCat backend (for example, from a previous session that lost network connectivity) are posted automatically.

If you want to explicitly sync purchases, for example, to handle a restore flow, call:

val customerInfo = Purchases.sharedInstance.awaitRestore()

This posts all current Play Store purchases for the user to RevenueCat and returns updated CustomerInfo.

The UpdatedCustomerInfoListener

Set this listener to receive CustomerInfo updates pushed by the SDK:

Purchases.sharedInstance.updatedCustomerInfoListener =
    UpdatedCustomerInfoListener { customerInfo ->
        updateUIForEntitlements(customerInfo)
    }

This is called after purchases, restores, and SDK-initiated refreshes. It fires on the main thread. Do not block it.