Untangling Android Back-Button Ad Gates: A Parallel, Priority-Ordered Redesign with Claude Code

The Redesign: Parallel, Independent, Declarative Gates

The new design fits in three sentences. Each concern becomes a gate that answers exactly one question. Gates know nothing about each other. Priority is declared in a single ordered list instead of in nesting.

// After: the exit flow as a first-match-wins pipeline of independent gates
interface ExitGate {
    val name: String
    fun evaluate(ctx: ExitContext): GateDecision
}
 
sealed class GateDecision {
    object Pass : GateDecision()                                  // not my turn -> next gate
    data class Consume(val action: () -> Unit) : GateDecision()   // handle it here, stop evaluating
}
 
class ExitFlowDispatcher(private val gates: List<ExitGate>) {
    /** Routes one back-press to exactly one gate.
     *  Returns false if no gate consumed it (= defer to normal back handling). */
    fun onExitRequested(ctx: ExitContext): Boolean {
        for (gate in gates) {
            when (val decision = gate.evaluate(ctx)) {
                is GateDecision.Consume -> {
                    GateLog.record(gate.name)     // always record who consumed it
                    decision.action()
                    return true
                }
                GateDecision.Pass -> continue
            }
        }
        GateLog.record("(pass-through)")          // record the silence, too
        return false
    }
}

Priority then becomes a list literal — something a code review can read as a spec.

// Priority is the order of this list. Nothing else.
val exitGates = listOf(
    adFreeGate,          // 1. ad-free users pass through, always, first
    modalCollisionGate,  // 2. never show anything on top of another modal
    reviewInductionGate, // 3. the review prompt outranks the ad
    frequencyCapGate,    // 4. interval cap -> pass through, but record it
    interstitialGate,    // 5. show the interstitial if loaded
)

Evaluation is first-match-wins: walk the list top to bottom, let the first gate that returns Consume do its work, and never evaluate the rest. "Billing outranks the review prompt" is now expressed by adFreeGate literally sitting on a higher line than reviewInductionGate. Adding a concern means writing one new gate and inserting one line — no existing gate changes.

One rule I held onto deliberately: evaluate must be side-effect free. The frequency-cap gate only answers "is the cap reached?"; incrementing the impression counter happens inside the interstitial gate's action, and only in the ad's on-shown callback. The original "unloaded fall-through skips the bookkeeping" bug existed precisely because judging and recording were tangled together.

One Source of Truth for "Ad-Free"

Extracting the gates surfaced a second structural problem. The answer to "may we show ads to this user?" was computed slightly differently in different screens. Some read billingManager.isPurchased directly. The temporary ad-free window granted for watching a rewarded ad lived in a separate manager, and some screens consulted it while others did not.

The fix was to make one class the only place that can answer the question.

// The ad-free decision lives here and nowhere else.
class AdFreeStatus(
    private val billing: BillingManager,
    private val rewardWindow: RewardAdFreeManager,
) {
    /** True if the user bought ad removal OR is inside a rewarded ad-free window */
    val isAdFree: Boolean
        get() = billing.isPurchased || rewardWindow.isActive
}
 
class AdFreeGate(private val status: AdFreeStatus) : ExitGate {
    override val name = "AdFreeGate"
    override fun evaluate(ctx: ExitContext): GateDecision =
        if (status.isAdFree) GateDecision.Consume { ctx.finishNormally() }
        else GateDecision.Pass
}

The step that paid for itself was asking Claude Code: "List every place outside the class that reads billingManager.isPurchased directly, and produce the diff that routes them through AdFreeStatus." It found nine direct references in my project. Two of them had never accounted for the rewarded unlock at all — meaning screens other than the exit flow could show ads to users who were legitimately inside an ad-free window. I could have done the grep myself, but going from "found" to "here is the reviewed diff" in one motion let me spend my attention on review instead of mechanics.

Because the rewarded window expires, rewardWindow.isActive checks the clock on every read. I considered caching the value per session and decided against it: a getter is cheap, and a stale "still ad-free" flag straddling the expiry moment is exactly the kind of inconsistency this refactor was meant to eliminate.

Wiring into OnBackPressedDispatcher, and the Double-Press Window

Overriding onBackPressed() has been deprecated since API 33, so the integration point is the OnBackPressedDispatcher. The Activity-side code shrinks to this:

// The Activity registers exactly one callback with the dispatcher
onBackPressedDispatcher.addCallback(this) {
    val consumed = exitFlow.onExitRequested(buildExitContext())
    if (!consumed) {
        isEnabled = false                          // disable self first
        onBackPressedDispatcher.onBackPressed()    // defer to the system default
        isEnabled = true
    }
}

Device testing added one more guard. Between the moment the show-ad action runs and the moment the interstitial actually covers the screen, there are a few hundred milliseconds in which the user can press back again. A 600 ms debounce at the dispatcher entry keeps a rapid double-press from running the gate evaluation twice.

There is also a forward-looking reason to keep evaluate side-effect free: predictive back on Android 14 and later. With predictive back, the preview begins before the user commits the gesture, so evaluation and commitment become separate moments. A judgment that is safe to run any number of times, with a single action that runs once at commit, is exactly the shape predictive back wants.

Working with Claude Code: Inventory, Decision Table, and Where I Said No

I delegated three areas to Claude Code on this project.

The first was path enumeration of the legacy handler. I handed it the old onBackPressed plus the related flag implementations and asked for every reachable execution path as a table of condition combinations and outcomes. It came back with 22 reachable paths. Nine of them were paths I could not map to any intended behavior. "The author cannot explain nine of his own code paths" was the single most persuasive argument for doing the refactor at all.

The second was the decision table and test generation for the new design. The request looked roughly like this:

I am sharing ExitFlowDispatcher and the five gate implementations.
I want to freeze the gate evaluation order as a specification.
Generate a JUnit 5 parameterized test that covers
(state combination x name of the consuming gate) exhaustively.
States: isAdFree / isModalShowing / reviewEligible / capReached / adLoaded
Output the decision table you derive the expectations from first.

The third was the AdFreeStatus reference consolidation described above.

Just as important were the two proposals I turned down. Claude Code initially suggested an event-bus style mechanism for gates to coordinate through, and separately suggested merging the frequency-cap gate into the interstitial gate. The first is plainly more machinery than an app this size needs; I prefer not to add a dependency for a problem a for-loop solves. The second would have quietly re-married "judging the interval" to "performing the show" — the exact coupling the refactor existed to remove. I explained the reasoning and asked it to keep the gates independent, which it did. Keeping final design judgment in human hands, and articulating why an alternative loses, matters more when pairing with an AI, not less.

Unit Tests That Freeze Priority as a Specification

Here is the cleaned-up version of the generated test. The decision table became the test data verbatim.

@ParameterizedTest
@CsvSource(
    // adFree, modal, review, cap,   loaded, expected consuming gate
    "true,   false, false,  false,  true,   AdFreeGate",
    "false,  true,  false,  false,  true,   ModalCollisionGate",
    "false,  false, true,   false,  true,   ReviewInductionGate",
    "false,  false, false,  true,   true,   FrequencyCapGate",
    "false,  false, false,  false,  true,   InterstitialGate",
    "false,  false, false,  false,  false,  (pass-through)",
)
fun exitFlowConsumesExactlyOneGateInDeclaredOrder(
    adFree: Boolean, modal: Boolean, review: Boolean,
    cap: Boolean, loaded: Boolean, expected: String,
) {
    val ctx = exitContext(adFree, modal, review, cap, loaded)
    val consumedGate = dispatcher.onExitRequestedRecording(ctx)
    assertEquals(expected, consumedGate)
}

Beyond these six representative rows, a generated exhaustive suite walks all 32 combinations. On the first run, 2 of the 32 failed — and neither failure was a bug in the new implementation. Both were rows where the expected value had inherited the old code's unintended behavior. Sitting with the decision table and settling, row by row, what each combination should actually do felt less like writing tests and more like excavating the specification that was never written down.

The practical payoff: changing priority is now a one-line reorder in the gate list plus the matching rows in the table. When I later wanted to test "review prompt below the frequency cap," the diff was exactly that — and nothing else moved.

Migration Pitfalls

The migration had more traps than the implementation, so here they are in the order I hit them.

• Ad-load timing during evaluation: if adLoaded flips mid-evaluation, results wobble. ExitContext is built as a snapshot at evaluation start, so one evaluation sees one consistent world.
• Where the frequency cap lives: it started in memory, so process death reset the counter. It now persists in DataStore, and the increment happens only in the ad's on-shown callback. Counting "times we actually showed" rather than "times we tried" turned out to be the operationally correct definition.
• Collisions with the review prompt: before the gate era, the exit ad and the review prompt could appear in the same frame. The modal-collision gate is the structural fix; the dialog-collision problem itself is written up separately in the ModalGate implementation memo for Android dialog collisions.
• Predictive back: as above, evaluation must stay side-effect free. If someone later adds a side effect to evaluate, the preview gesture alone will mutate state — a bug that will look supernatural in reports.
• Unlogged pass-throughs: adding one line to record the silent path is what turned "the ad never shows on my device" tickets into two-minute lookups. The log line is as valuable as the gate design itself.

A Few Weeks In

v2.1.0 shipped with this redesign through a staged rollout (5% then 25%, 50%, 100%), watching crash-free users stay at or above 99.7% before each expansion. The monitoring setup is the same one described in my staged rollout and crash monitoring notes for Google Play. The same release also fixed a long-standing RecyclerView crash, which has its own write-up in the defensive-copy fix for a RecyclerView crash I could not reproduce.

Since the rollout completed, exit-ad bug reports stand at zero. AdMob exit-interstitial impressions have settled into the range the frequency cap was designed to produce. The biggest day-to-day difference is investigation time: GateLog records which gate consumed each back-press, so "why did this user see no ad?" is answered by reading one log line rather than rebuilding a repro environment, which used to consume half a day.

The honest revenue answer is "still measuring." Closing the over-firing path trimmed short-term impressions slightly. After running AdMob in production for close to a decade, I expect fewer ad complaints in reviews to be worth more than those impressions over the long run — app-business compounding tends to favor trust.

Your Next Step: Count Your Gates Before Writing Any Code

If your own exit flow has become the code nobody wants to touch, do one thing before refactoring: write down, as a plain list, every question your back button currently answers. Mine had five. If you find three or more, the nesting almost certainly hides paths you cannot explain. That list of questions becomes your gate list, the gate list becomes your priority spec, and only then is it worth opening the editor.

If you are facing the same structural trap, I hope this record saves you some of the detours it cost me.