Integrating Pbl

Integrating the Play Billing Library

You are wiring the Play Billing Library into an Android app. This skill covers the client side setup: adding the dependency, building BillingClient, managing the connection, and querying products. Follow the phases in order.

Phase 0: Intent

Confirm what the caller actually wants before you touch code. Pick one:

If the request is ambiguous, ask. Do not write Gradle edits or Kotlin until you know the target state.

Phase 1: Discovery

Inspect the project before changing anything.

Check the Gradle setup:

grep -r "com.android.billingclient" --include="*.gradle*"

Check existing BillingClient usage:

grep -rn "BillingClient" --include="*.kt" --include="*.java" src/

Record these facts:

If you find multiple BillingClient instances in one process, flag it. One instance per process is the rule.

Phase 2: Plan

Before writing code, pick a connection strategy and confirm with the caller.

Then decide:

1. Callback style or KTX coroutine style. If coroutines are already the norm in the project, pick KTX.
2. Auto reconnection on or off. Default to on unless you need manual control.
3. Which product IDs and types (INAPP, SUBS) the initial query covers. Batch up to 20 per call.

Write the plan down. One BillingClient owner, one listener, one connection strategy.

Phase 3: Execute

Step 1 Add the dependency

In the module build.gradle.kts:

dependencies {
    implementation("com.android.billingclient:billing-ktx:9.0.0")
}

The billing-ktx artifact pulls in the base library plus coroutine extensions. Drop -ktx if you do not want KTX.

Step 2 Build the BillingClient

Use applicationContext to avoid activity leaks:

val billingClient = BillingClient.newBuilder(appContext)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(
        PendingPurchasesParams.newBuilder().build()
    )
    .enableAutoServiceReconnection()
    .build()

All four calls are required for a working PBL 9 setup. Missing setListener throws IllegalArgumentException. Missing enablePendingPurchases throws IllegalStateException.

Step 3 Wire the PurchasesUpdatedListener

One listener per client. Dispatch from it if other components need to react:

val purchasesUpdatedListener =
    PurchasesUpdatedListener { result, purchases ->
        when (result.responseCode) {
            BillingResponseCode.OK ->
                purchases?.forEach(::handlePurchase)
            BillingResponseCode.USER_CANCELED -> Unit
            else -> logError(result)
        }
    }

The callback fires on the main thread and can fire while the app is in the background. Update a repository or state holder, not UI directly. Never force unwrap purchases; it is null on non OK responses.

Step 4 Start the connection

Callback form:

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(result: BillingResult) {
        if (result.responseCode == BillingResponseCode.OK) {
            onBillingReady()
        }
    }
    override fun onBillingServiceDisconnected() { /* auto retry */ }
})

KTX form:

val result = billingClient.startConnection()
if (result.responseCode == BillingResponseCode.OK) {
    onBillingReady()
}

Do not call billing methods before onBillingSetupFinished fires with OK. Queue pending work and flush on each successful connect.

Step 5 Query product details

Build the product list, mix INAPP and SUBS in one call, keep each batch at or under 20 products:

val products = listOf(
    QueryProductDetailsParams.Product.newBuilder()
        .setProductId("premium_monthly")
        .setProductType(ProductType.SUBS)
        .build()
)
val params = QueryProductDetailsParams.newBuilder()
    .setProductList(products)
    .build()

Callback form:

billingClient.queryProductDetailsAsync(params) { result, list ->
    if (result.responseCode == BillingResponseCode.OK) {
        displayProducts(list)
    }
}

KTX form:

val result = billingClient.queryProductDetails(params)
val details = result.productDetailsList

Do not cache ProductDetails across sessions. Prices can change; re query each time you display products.

Step 6 Handle UnfetchedProduct results

PBL 8 and 9 return a QueryProductDetailsResult that may include UnfetchedProduct entries. Branch on the per product response code:

Cap retries at two or three attempts. Show the products you did fetch and log the rest.

Step 7 Handle disconnection

With enableAutoServiceReconnection(), PBL retries for you using exponential backoff. Your job is only to retry the in flight operation that failed with SERVICE_DISCONNECTED. If you disabled auto reconnection, implement backoff yourself starting at one second and capping near fifteen seconds.

Check billingClient.isReady before issuing a call if you need a fast path. Always call endConnection() when the owning scope is destroyed.

Phase 4: Verify

Before you mark the integration done, confirm each of these:

If any row fails, return to Phase 2 and revise the plan. Do not paper over a failing check.

References

• Full chapter

• Google Play Billing Library release notes and migration guides for version specific details.