Where Is the Source of Truth for Billing State? Designing the ad-free Pattern with Antigravity

AdFreeManager: The Single Source

AdFreeManager becomes the sole origin of billing state in the app. Its design reflects a deliberate choice: callers don't need to know whether the user is ad-free because they purchased the product or because they watched a rewarded ad. That distinction is encapsulated inside.

class AdFreeManager private constructor(
    private val billingManager: BillingManager,
    private val rewardManager: RewardedAdManager
) {
    val isAdFree: Boolean
        get() = billingManager.isPurchased() || rewardManager.isAdFreeSession
 
    val isPermanentlyAdFree: Boolean
        get() = billingManager.isPurchased()
 
    val isSessionAdFree: Boolean
        get() = rewardManager.isAdFreeSession && !billingManager.isPurchased()
 
    companion object {
        @Volatile private var instance: AdFreeManager? = null
 
        fun getInstance(
            billingManager: BillingManager,
            rewardManager: RewardedAdManager
        ): AdFreeManager = instance ?: synchronized(this) {
            instance ?: AdFreeManager(billingManager, rewardManager).also {
                instance = it
            }
        }
    }
}

The singleton pattern guarantees consistent state across the entire app. @Volatile combined with synchronized prevents race conditions during instance creation in a multithreaded environment — the double-checked locking pattern, properly implemented in Kotlin.

Exposing three properties rather than one is intentional. Most locations should use isAdFree. But some features want to distinguish between permanent and session-only access — for example, showing a "thank you for your purchase" message only to permanent subscribers, or tracking rewarded ad engagement separately. The three-property design makes those distinctions explicit without pushing the logic back into callers.

BillingManager: Bridging Google Play Billing

BillingManager wraps Google Play Billing Library and handles the asynchronous reality of purchase verification. The design decision that matters most here is using StateFlow for purchase state.

StateFlow is a Kotlin Coroutines construct: it holds a value and automatically notifies collectors when that value changes. For purchase state, StateFlow fits naturally because purchase events — completion, restoration, revocation — arrive asynchronously. A StateFlow-based design means the UI reacts to those events automatically without polling or manual refreshes. Configuration changes (screen rotation) trigger automatic re-emission of the current value, so UI state is never lost.

class BillingManager(private val context: Context) {
 
    private var billingClient: BillingClient? = null
    private val _isPurchasedFlow = MutableStateFlow(false)
    val isPurchasedFlow: StateFlow<Boolean> = _isPurchasedFlow.asStateFlow()
 
    init { setupBillingClient() }
 
    private fun setupBillingClient() {
        billingClient = BillingClient.newBuilder(context)
            .setListener { billingResult, purchases ->
                if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                    handlePurchases(purchases)
                }
            }
            .enablePendingPurchases(
                PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()
            )
            .build()
        connectAndVerify()
    }
 
    private fun connectAndVerify() {
        billingClient?.startConnection(object : BillingClientStateListener {
            override fun onBillingSetupFinished(billingResult: BillingResult) {
                if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                    queryExistingPurchases()
                }
            }
            override fun onBillingServiceDisconnected() { }
        })
    }
 
    private fun queryExistingPurchases() {
        val params = QueryPurchasesParams.newBuilder()
            .setProductType(BillingClient.ProductType.INAPP)
            .build()
        billingClient?.queryPurchasesAsync(params) { billingResult, purchases ->
            if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
                handlePurchases(purchases)
            }
        }
    }
 
    private fun handlePurchases(purchases: List<Purchase>?) {
        val hasPurchased = purchases?.any { purchase ->
            purchase.products.contains(PRODUCT_ID_AD_FREE) &&
            purchase.purchaseState == Purchase.PurchaseState.PURCHASED
        } ?: false
        _isPurchasedFlow.value = hasPurchased
    }
 
    fun isPurchased(): Boolean = _isPurchasedFlow.value
 
    companion object {
        const val PRODUCT_ID_AD_FREE = "remove_ads"
    }
}

Notice that handlePurchases is called in two places: through the setListener callback when a purchase completes, and through queryExistingPurchases at connection setup. This ensures the state is accurate both on app launch (for existing purchasers) and immediately after a new purchase completes.

ModalGate: Preventing Dialog Conflicts

The Source of Truth principle extends naturally to dialog management. My wallpaper app has three dialogs that can potentially surface simultaneously:

• PaywallDialog: Ad removal upsell
• ReviewInductionDialog: In-app review prompt
• RewardedInterstitialDialog: Rewarded ad explanation and consent

When these compete, user experience breaks down in ways that are difficult to reproduce but easy to complain about in reviews. A user trying to dismiss the paywall gets the review prompt instead. A user about to watch a rewarded ad gets interrupted by another dialog. These are real scenarios that generated real user complaints.

The underlying problem is that each dialog has no visibility into whether another is already showing. The solution is a centralized gatekeeper — a singleton through which all dialogs attempt to acquire display rights.

object ModalGate {
    private val activeModal = AtomicReference<String?>(null)
 
    fun tryShow(tag: String): Boolean {
        return activeModal.compareAndSet(null, tag)
    }
 
    fun dismiss(tag: String) {
        activeModal.compareAndSet(tag, null)
    }
 
    fun isShowing(): Boolean = activeModal.get() != null
    fun currentTag(): String? = activeModal.get()
}

AtomicReference.compareAndSet(expected, update) swaps the value only when it currently matches expected, returning true on success. This is a lock-free compare-and-swap: thread-safe by construction, no risk of deadlocks. The protocol is simple — try to acquire, show on success, dismiss gracefully on failure.

class PaywallDialog : DialogFragment() {
 
    override fun onStart() {
        super.onStart()
        if (!ModalGate.tryShow(TAG)) {
            dismissAllowingStateLoss()
        }
    }
 
    override fun onDismiss(dialog: DialogInterface) {
        super.onDismiss(dialog)
        ModalGate.dismiss(TAG)
    }
 
    override fun onDestroyView() {
        super.onDestroyView()
        ModalGate.dismiss(TAG)
    }
 
    companion object {
        const val TAG = "PaywallDialog"
    }
}

The onDestroyView dismiss is a safety net for cases where onDismiss is never called — when the app is killed in the background due to memory pressure, for example. The double-dismiss is safe because compareAndSet is idempotent when the value doesn't match.

Four Traps I Walked Into

This design was not born clean. Here are the problems I encountered during implementation.

Trap 1: BillingClient connection timing

BillingClient connects asynchronously. Calling isPurchased() immediately on app launch returns false before connection is established — meaning a legitimate purchaser sees an AdMob banner for a brief moment at startup. This is surprising and erodes trust.

What I did at the time was hold the SplashScreen until the BillingClient connection and the purchase query had both finished, so the StateFlow value was settled before the home screen appeared. Wait a little longer, show fewer wrong ads.

It reduced the problem. It did not remove it. I come back to why, and to the design I replaced it with, in "Don't Call 'I Don't Know Yet' False" further down.

Trap 2: Stale ModalGate state after process death

When an app returns to the foreground after being killed in the background, ModalGate.activeModal can retain a stale tag if the dialog was destroyed without calling onDismiss. The result: subsequent tryShow calls all return false, permanently preventing any dialog from appearing.

The fix: call ModalGate.dismiss(TAG) in both onDismiss and onDestroyView. The compareAndSet semantics make the duplicate call safe — if the tag doesn't match (because another dialog is active), nothing changes.

Trap 3: Singleton state pollution in unit tests

As a Kotlin object, ModalGate is a process-lifetime singleton. Test cases sharing the same singleton instance interfere with each other. A test that acquires the gate but doesn't release it causes all subsequent tests' tryShow calls to fail.

The fix: add a @VisibleForTesting fun reset() method to ModalGate that clears activeModal, and call it in each test's @Before. The annotation documents the intent without restricting access.

Trap 4: The three-day acknowledgePurchase deadline

Since Billing Library 2.0, purchases that are not acknowledged within three days are automatically refunded. I learned this the uncomfortable way: the purchase flow looked healthy, yet days later a user reported that their purchase had been "cancelled." Tracing it back, the acknowledgePurchase call existed only in the immediate purchase callback — any purchase that missed that path due to a dropped connection or process death silently expired unacknowledged.

The fix is to acknowledge from the query path as well, not just the purchase callback:

private fun handlePurchase(purchase: Purchase) {
    if (purchase.purchaseState == Purchase.PurchaseState.PURCHASED
        && !purchase.isAcknowledged) {
        val params = AcknowledgePurchaseParams.newBuilder()
            .setPurchaseToken(purchase.purchaseToken)
            .build()
        billingClient?.acknowledgePurchase(params) { result ->
            if (result.responseCode != BillingClient.BillingResponseCode.OK) {
                // Will be retried on the next launch query — placing the call
                // on this path is itself the retry mechanism.
            }
        }
    }
}

Because the query runs on every launch and feeds the Source of Truth, there is exactly one natural place for this logic — and simply opening the app repairs any unacknowledged purchase. One more quiet benefit of centralization.

Don't Call "I Don't Know Yet" False

I would no longer recommend the SplashScreen fix from Trap 1. It solves the problem with time, and time is exactly what you don't control on a thin connection or on a morning when the Play Store is slow to answer.

The cause was never the length of the wait. It was the type. A MutableStateFlow(false) collapses "this user has not purchased" and "I don't know yet" into the same false, and the ad slot has no way to tell them apart. That is where the banner shown to a paying customer comes from.

I built a small model to see how wide that window really is. Let t_ui be the moment the ad slot first reads isAdFree, and t_bill the moment the queryPurchasesAsync callback returns after startConnection. Sweeping t_ui from 0 to 1,000ms and t_bill from 0 to 2,000ms in 10ms steps gives a grid of 20,301 points. These are not device measurements — it's a fixed-parameter model, and all it shows is how much of the ordering space the bug occupies.

On that grid, the false-by-default design showed an ad to a purchasing user at 15,150 points, or 74.6%. Restricted to the region where t_bill exceeds 300ms, it's 85.5%. And lengthening the splash only shaves that area down; it never reaches zero.

To reach zero you have to wait past the right edge of the grid — longer than the worst response you are willing to imagine. Real t_bill has no upper bound, so the approach never finishes. You end up showing every user a two-second white screen and still missing some of them.

So I dropped the default value and made the state itself a third thing.

sealed interface AdFreeState {
    data object Unknown : AdFreeState
    data class Known(val adFree: Boolean, val source: Source) : AdFreeState
 
    enum class Source { CACHE, BILLING, REWARD }
}

BillingManager now seeds from the cache as a provisional truth and lets the Google Play response overwrite it. A response it cannot interpret is ignored rather than read as false.

private val _state = MutableStateFlow<AdFreeState>(AdFreeState.Unknown)
val state: StateFlow<AdFreeState> = _state.asStateFlow()
 
init {
    // Provisional. The billing response always overwrites this.
    if (prefs.getBoolean(KEY_AD_FREE, false)) {
        _state.value = AdFreeState.Known(adFree = true, source = Source.CACHE)
    }
    setupBillingClient()
}
 
private fun handlePurchases(result: BillingResult, purchases: List<Purchase>?) {
    if (result.responseCode != BillingClient.BillingResponseCode.OK) return
    if (purchases == null) return  // An OK-but-empty response is not "not purchased"
 
    val hasPurchased = purchases.any { purchase ->
        purchase.products.contains(PRODUCT_ID_AD_FREE) &&
        purchase.purchaseState == Purchase.PurchaseState.PURCHASED
    }
    prefs.edit().putBoolean(KEY_AD_FREE, hasPurchased).apply()
    _state.value = AdFreeState.Known(adFree = hasPurchased, source = Source.BILLING)
}

Compared with the earlier version this looks like nothing more than dropping a ?: false. The meaning is quite different: the path that revoked ad-free the instant a network call failed is now closed.

On the UI side, Unknown maps to "don't draw yet" rather than "show an ad."

lifecycleScope.launch {
    repeatOnLifecycle(Lifecycle.State.STARTED) {
        adFreeManager.state.collect { state ->
            when (state) {
                is AdFreeState.Unknown -> adContainer.isVisible = false
                is AdFreeState.Known -> adContainer.isVisible = !state.adFree
            }
        }
    }
}

Seeding from the cache is what does the real work. On the same grid, wrong impressions fall from 15,150 points to 201 (1.0%), and what remains is only the case where the ad slot is laid out before the cache read completes. A 5ms read beats a two-second splash.

The moment you round "not yet known" down to false, you no longer have a single source of truth. Holding uncertainty as a type, and carrying it all the way to the UI, turned out to be part of the job — something I only understood after rebuilding it.

There was one more hole in that older code: onBillingServiceDisconnected() had an empty body. Nothing reconnected and nothing re-queried, so a purchase restored on another device never reached the app until the process was started again. It now reconnects with exponential backoff and re-runs queryPurchasesAsync in onResume — which the one-time purchase lifecycle guide lists as one of the ways to pick up a purchase.

Billing Library Deadlines Are Part of the Design

Every version of the Play Billing Library runs on a two-year deprecation cycle, with a deadline for new apps and updates and a separate extension deadline. The table lives in Google's deprecation FAQ.

As I revise this in September 2026, an app still on v7 can no longer submit a new release or an update, and any extension runs out on November 1, 2026. Version 8 is the floor, and a migration guide for version 9 is already published.

If the Play Console warning persists after you have upgraded, check that com.google.android.play.billingclient.version still survives in your merged AndroidManifest.xml. Manifest merging can drop it, and I lost half a day to that one.

This is where the wrapper earns its keep. When the migration touches handlePurchases, it touches one file. Had the billing checks stayed scattered across five call sites, every deadline would have meant five diffs and one thing quietly left behind.

Using Antigravity as an Architecture Partner

The designs above came through conversation with Antigravity. I want to be specific about what that means, because "talk to the AI" is vague advice that often produces shallow results.

The interactions that generated useful output looked like this. "Both BillingManager and SharedPreferences hold purchase state. Which should be the Source of Truth? Give me the reasoning, not just the answer." Or: "I want to prevent competing dialogs. Show me two approaches — one with AtomicReference and one without — and explain the tradeoffs." Or: "Here is my implementation. List the potential failure modes, specifically around threading and Fragment lifecycle."

The pattern is: ask for reasoning, not just code. Ask for alternatives, not just recommendations. Ask for failure modes, not just happy paths. When Antigravity explains why before generating the code, that reasoning becomes part of your architecture vocabulary — not just a copied snippet.

Even with AI-generated code, I read through each line before committing it. Reading the generated code is not overhead — it is the moment a proposed design becomes my own design, and it is where most of my understanding actually happens.

UI Integration: Reactive Ad Visibility with StateFlow

Here is how the three components come together in practice.

class MyApplication : Application() {
    lateinit var billingManager: BillingManager
        private set
    lateinit var rewardedAdManager: RewardedAdManager
        private set
    lateinit var adFreeManager: AdFreeManager
        private set
 
    override fun onCreate() {
        super.onCreate()
        billingManager = BillingManager(this)
        rewardedAdManager = RewardedAdManager()
        adFreeManager = AdFreeManager.getInstance(billingManager, rewardedAdManager)
    }
}
 
class HomeFragment : Fragment() {
    private val app by lazy { requireActivity().application as MyApplication }
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        viewLifecycleOwner.lifecycleScope.launch {
            app.billingManager.isPurchasedFlow.collect { _ ->
                updateAdVisibility()
            }
        }
    }
 
    private fun updateAdVisibility() {
        binding.bannerAdView.visibility =
            if (app.adFreeManager.isAdFree) View.GONE else View.VISIBLE
    }
}

When a purchase completes, isPurchasedFlow updates. Every Fragment collecting it calls updateAdVisibility() automatically. No manual screen refresh. No "please restart the app to apply your purchase." The design eliminates the friction that the bug was creating.

The Long-Term Return on Architectural Investment

Centralized billing state design pays dividends that compound over time. When adding a new subscription tier, the change lives in AdFreeManager.isAdFree. When adding a new ad format, the change lives in RewardedAdManager. When adding a new dialog, it plugs into ModalGate and inherits conflict prevention automatically.

The alternative is continuing to update scattered conditions spread across a codebase that grows more fragile with each feature. Maintaining a production app solo over many years has taught me that the problems most likely to damage user trust are the ones that feel intermittent and hard to reproduce — exactly the class of bugs that distributed billing state creates.

Where to Start Today

Run this against your own codebase:

grep -rn "is_ad_free\|isPurchased\|isAdFree\|isAdRemoved" \
  app/src/main/java/ --include="*.kt" --include="*.java" | wc -l

If you get more than ten results, a Source of Truth refactor is worth planning. Show Antigravity your existing billing state code and ask for help identifying the canonical source. Have the conversation about architecture before asking for code. The design clarity you get from that conversation is more valuable than any individual implementation.

If you decide to refactor, this order has worked well for me:

1. Inventory every billing-state reference in your codebase using the grep above
2. Introduce BillingManager and confine all Google Play Billing queries to that single class
3. Create AdFreeManager and migrate the inventoried references to isAdFree, one call site at a time
4. Add ModalGate last to centralize dialog presentation — it is independent of the first three steps

Migrating one call site at a time, rather than rewriting everything at once, lets you verify behavior continuously and keeps the refactor safe.

Building this foundation doesn't produce visible features. But it changes what's possible afterward — and how sustainable the development becomes over years.