@mpgd/capacitor-play-billing 0.5.0 → 0.6.0

package/README.md

@@ -150,6 +150,71 @@ discarded. The plugin still never acknowledges or consumes;
 `isAcknowledged: false` on a purchased entry marks it unfinished for the
 backend finalizer.
 
+### Purchase sheet facts
+
+The provider offers `CommerceProvider.presentation` (see "Store sheet facts"
+in the `@mpgd/adapter-capacitor` README), so the gateway keeps the game
+paused, and the game runtime keeps ads out, until the Play sheet is gone
+rather than until a purchase result. The native plugin observes the sheet
+from the activity lifecycle, never from `onPurchasesUpdated`:
+
+- `open` when a Billing Library activity
+  (`com.android.billingclient.api.ProxyBillingActivity` or `...V2`, the
+  translucent activity `launchBillingFlow` starts in the app process once it
+  returns OK) is created during the flow, however late;
+- `closed` when an app activity that is not a billing activity resumes after
+  it (the game's activity sits below the sheet in the same task), with
+  `reason: 'interrupted'` when the app is torn down (finishing), or with
+  `reason: 'timeout'` after 15 minutes without the game's activity resuming;
+- `not-started` when the flow ended without a billing activity: a refusal
+  before the launch, or a launch that brought nothing over the game. After a
+  launch attempt the plugin waits 500 ms for the activity, and while the
+  game's activity is paused (something is coming over it) the verdict waits
+  until it resumes (`not-started`), a billing activity appears (`open`), or
+  10 seconds pass.
+
+The plugin answers `PLAY_BILLING_BUSY` to a new purchase until the previous
+flow's terminal fact. A pending purchase, a purchase made outside the app,
+and the 180-second call timeout are not sheet facts. When the call times out
+before the flow ever reached `launchBillingFlow` (stuck before the launch),
+the plugin ends that flow `not-started` and cancels it; a flow that launched
+answers `presentation: 'requested'` when nothing was observed yet, and the
+provider then reports the sheet `unknown` and waits for the native verdict
+instead of assuming a sheet. Facts reach JavaScript as `purchasePresentation`
+events (retained until a listener attaches, keyed by a random id per call)
+and in the `presentation` field of the `purchase` answer or rejection data.
+The adapter adds a 15-minute safety timeout.
+
+The host activity must handle configuration changes itself, as Capacitor's
+`BridgeActivity` does by default (`android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"`):
+an activity recreated while the Play sheet is up loses the web view and the
+plugin's observations. The plugin then claims no `closed` for a sheet that
+may still be up (it reports `interrupted` only when the activity is
+finishing), and the reference shell's manifest check
+(`pnpm validate:capacitor-alignment`) keeps the attribute.
+
+`getPresentationSupport` declares the facts. A web bundle running on a native
+build from before them (a live update) gets `UNIMPLEMENTED` there: while an
+adapter follows the facts, the store then reads `configuration-required` (the
+shop sells nothing and the reconciler spends no idempotency key), and a
+purchase that still gets through is refused with `CONFIGURATION_REQUIRED` /
+`PLAY_BILLING_PRESENTATION_UNSUPPORTED` instead of opening a sheet the game
+would wait on; recovery is unaffected. `purchasePresentation: false` on the
+provider keeps the result-based pause of earlier releases. Google documents
+that `launchBillingFlow` returning `OK` "indicates a successful launch"
+([Integrate the Google Play Billing Library](https://developer.android.com/google/play/billing/integrate#launch));
+the proxy activity names are the Billing Library 9.1.0 implementation (its
+manifest declares both, in the app process), not a documented contract, so a
+Billing Library or OpenIAP upgrade must re-check them.
+
+Device acceptance (not run; no device was available): the sheet cancelled by
+its close button and by the back button, a completed purchase, a pending
+(slow card) purchase, the app backgrounded with the sheet up and resumed, and
+a rotation with the sheet up. Each must pause the game from `open` to
+`closed` and never resume it under the sheet. The steps and expected signals
+are in the kit's
+[purchase device acceptance checklist](https://github.com/imjlk/mpgd-kit/blob/main/docs/PURCHASE_DEVICE_ACCEPTANCE.md).
+
 ### Generated games
 
 Games generated by `mpgd game create` (and the kit's private starter) ship

package/android/src/main/java/dev/mpgd/capacitor/playbilling/CapacitorPlayBillingPlugin.kt

@@ -1,5 +1,8 @@
 package dev.mpgd.capacitor.playbilling
 
+import android.app.Activity
+import android.app.Application
+import android.os.Bundle
 import android.os.Handler
 import android.os.Looper
 import android.util.Log
@@ -18,7 +21,9 @@ import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.SupervisorJob
 import kotlinx.coroutines.cancel
+import kotlinx.coroutines.currentCoroutineContext
 import kotlinx.coroutines.delay
+import kotlinx.coroutines.ensureActive
 import kotlinx.coroutines.launch
 import org.json.JSONException
 
@@ -56,6 +61,43 @@ class CapacitorPlayBillingPlugin : Plugin() {
      */
     private var timedOutProductId: String? = null
 
+    /** Sheet facts of the flow in progress; see `PurchasePresentationTracker`. */
+    private val presentation = PurchasePresentationTracker { id, state, reason ->
+        if (state == PurchasePresentationTracker.OPEN) {
+            armSheetTimeout(id)
+        } else {
+            sheetTimeout?.cancel()
+            sheetTimeout = null
+        }
+        notifyPresentation(id, state, reason)
+    }
+    private var sheetTimeout: Job? = null
+    private var purchaseJob: Job? = null
+    private var lateLaunchBound: Job? = null
+    private var presentationId: String? = null
+    private var lifecycleApplication: Application? = null
+
+    // Every activity of the app process, the Billing Library's proxy
+    // activities included; callbacks arrive on the main thread.
+    private val activityCallbacks = object : Application.ActivityLifecycleCallbacks {
+        override fun onActivityCreated(activity: Activity, savedInstanceState: Bundle?) {
+            presentation.onActivityCreated(activity.javaClass.name)
+        }
+
+        override fun onActivityResumed(activity: Activity) {
+            presentation.onActivityResumed(activity.javaClass.name)
+        }
+
+        override fun onActivityPaused(activity: Activity) {
+            presentation.onActivityPaused(activity.javaClass.name)
+        }
+
+        override fun onActivityStarted(activity: Activity) = Unit
+        override fun onActivityStopped(activity: Activity) = Unit
+        override fun onActivitySaveInstanceState(activity: Activity, outState: Bundle) = Unit
+        override fun onActivityDestroyed(activity: Activity) = Unit
+    }
+
     override fun load() {
         try {
             connection = OpenIapPlayConnection.open(context) { purchase ->
@@ -67,19 +109,42 @@ class CapacitorPlayBillingPlugin : Plugin() {
             logUnexpected("provider load", error)
             providerError = "OpenIAP could not load the Google Play provider."
         }
+        lifecycleApplication = (context.applicationContext as? Application)?.also {
+            it.registerActivityLifecycleCallbacks(activityCallbacks)
+        }
     }
 
     override fun handleOnDestroy() {
+        // Nothing is observed after this. A finishing app reports a sheet
+        // still open as closed (`interrupted`); an activity that is only
+        // recreated (a configuration change the manifest does not handle)
+        // may leave the Play sheet up, so nothing is claimed for it.
+        presentation.onTeardown(reportClosed = activity?.isChangingConfigurations != true)
+        lateLaunchBound?.cancel()
         activePurchase?.let { call ->
+            val id = presentationId
             clearActivePurchase(call)
-            call.reject("Purchase flow was interrupted.", "PLAY_BILLING_INTERRUPTED")
+            call.reject("Purchase flow was interrupted.", "PLAY_BILLING_INTERRUPTED", null, presentationData(id))
         }
+        lifecycleApplication?.unregisterActivityLifecycleCallbacks(activityCallbacks)
+        lifecycleApplication = null
         scope.cancel()
         connection?.close()
         connection = null
         super.handleOnDestroy()
     }
 
+    /**
+     * Declares the sheet facts this native code reports (`purchasePresentation`
+     * events and the `presentation` field of `purchase` answers). A plugin
+     * build without this method answers `UNIMPLEMENTED`, and the TypeScript
+     * SDK then sells nothing that would wait for facts.
+     */
+    @PluginMethod
+    fun getPresentationSupport(call: PluginCall) {
+        call.resolve(JSObject().put("purchasePresentation", PurchasePresentationTracker.PROTOCOL_VERSION))
+    }
+
     @PluginMethod
     fun getProducts(call: PluginCall) {
         onMain { getProductsOnMain(call) }
@@ -128,51 +193,111 @@ class CapacitorPlayBillingPlugin : Plugin() {
         val productId = call.getString("productId")
         val accountId = call.getString("obfuscatedAccountId")
         val selectedOfferToken = call.getString("offerToken")
+        // Correlates this call's sheet facts; sent only by a TypeScript SDK
+        // that reads them. Without it the flow reports no facts, as before.
+        val requestedPresentationId = call.getString("presentationId")
+        if (requestedPresentationId != null &&
+            !PurchasePresentationTracker.isValidPresentationId(requestedPresentationId)
+        ) {
+            call.reject(
+                "The presentation id is invalid.",
+                "PLAY_BILLING_INVALID_REQUEST",
+                null,
+                JSObject().put("presentation", PurchasePresentationTracker.NOT_STARTED),
+            )
+            return
+        }
         if (productId == null || productId.trim().isEmpty() || accountId == null ||
             accountId.trim().isEmpty() || accountId.length > 64
         ) {
-            call.reject("Product and account identifiers are required.", "PLAY_BILLING_INVALID_REQUEST")
+            rejectNotStarted(call, requestedPresentationId, "Product and account identifiers are required.", "PLAY_BILLING_INVALID_REQUEST")
+            return
+        }
+        val active = connection
+        if (active == null) {
+            rejectNotStarted(
+                call,
+                requestedPresentationId,
+                providerError ?: "Google Play Billing is not configured.",
+                "PLAY_BILLING_CONFIGURATION_ERROR",
+            )
             return
         }
-        val active = connectionOrReject(call) ?: return
         // OpenIAP holds one flow at a time, including one whose call already
-        // timed out here; a second flow is busy until OpenIAP releases it.
-        if (activePurchase != null || flowInProgress) {
-            call.reject("Another purchase is already in progress.", "PLAY_BILLING_BUSY")
+        // timed out here; a second flow is busy until OpenIAP releases it, and
+        // until the sheet of the last one is gone (its `closed` is still owed).
+        if (activePurchase != null || flowInProgress || presentation.active) {
+            rejectNotStarted(call, requestedPresentationId, "Another purchase is already in progress.", "PLAY_BILLING_BUSY")
             return
         }
         activePurchase = call
         activeProductId = productId
+        presentationId = requestedPresentationId
         timedOutProductId = null
         flowInProgress = true
+        requestedPresentationId?.let { presentation.begin(it) }
         purchaseTimeout = scope.launch {
             delay(PURCHASE_TIMEOUT_MILLIS)
             if (activePurchase === call) {
+                val id = presentationId
+                // A flow that never reached `launchBillingFlow` (stuck before
+                // the launch) is ended here, `not-started`, and cancelled, so
+                // the game is not held for a sheet that cannot come. A
+                // launched flow keeps running and reports its sheet as events.
+                if (id != null && presentation.cancelBeforeLaunch(id)) {
+                    purchaseJob?.cancel()
+                }
                 timedOutProductId = activeProductId
                 clearActivePurchase(call)
-                call.reject("Purchase confirmation timed out; requery owned purchases.", "PLAY_BILLING_TIMEOUT")
+                // The sheet may still be up: its facts keep arriving as events.
+                call.reject(
+                    "Purchase confirmation timed out; requery owned purchases.",
+                    "PLAY_BILLING_TIMEOUT",
+                    null,
+                    presentationData(id),
+                )
             }
         }
-        scope.launch {
+        purchaseJob = scope.launch {
             val resolution = try {
-                runPurchase(active, productId, accountId, selectedOfferToken)
-            } catch (error: CancellationException) {
-                throw error
-            } catch (error: OpenIapError) {
-                if (PlayBillingPolicy.isCancellation(error)) {
-                    PurchaseResolution.Cancelled
-                } else {
-                    PurchaseResolution.Failed(PlayBillingPolicy.errorCode(error), billingMessage(error))
+                val outcome = try {
+                    runPurchase(active, productId, accountId, selectedOfferToken, requestedPresentationId)
+                } catch (error: CancellationException) {
+                    throw error
+                } catch (error: OpenIapError) {
+                    if (PlayBillingPolicy.isCancellation(error)) {
+                        PurchaseResolution.Cancelled
+                    } else {
+                        PurchaseResolution.Failed(PlayBillingPolicy.errorCode(error), billingMessage(error))
+                    }
+                } catch (error: Exception) {
+                    logUnexpected("purchase", error)
+                    PurchaseResolution.Failed("PLAY_BILLING_ERROR", "Google Play Billing failed.")
                 }
-            } catch (error: Exception) {
-                logUnexpected("purchase", error)
-                PurchaseResolution.Failed("PLAY_BILLING_ERROR", "Google Play Billing failed.")
+                // `launchBillingFlow` was called but no billing activity was
+                // seen yet: give one that was just started time to be created
+                // before the flow counts as never shown.
+                if (requestedPresentationId != null &&
+                    presentation.awaitsLaunchObservation(requestedPresentationId)
+                ) {
+                    delay(LAUNCH_OBSERVATION_GRACE_MILLIS)
+                }
+                outcome
             } finally {
+                requestedPresentationId?.let { id ->
+                    presentation.onFlowEnded(id)
+                    // The game's activity is still paused after a launch
+                    // attempt: the verdict waits for it (or a late billing
+                    // activity), bounded here. The flow stays busy meanwhile.
+                    if (presentation.isTracking(id) && presentation.openPresentationId == null) {
+                        armLateLaunchBound(id)
+                    }
+                }
                 // Released on every path, so one failure never leaves later
                 // purchases answering PLAY_BILLING_BUSY until a restart.
                 flowInProgress = false
             }
-            settlePurchase(call, productId, resolution)
+            settlePurchase(call, productId, requestedPresentationId, resolution)
         }
     }
 
@@ -181,6 +306,7 @@ class CapacitorPlayBillingPlugin : Plugin() {
         productId: String,
         accountId: String,
         selectedOfferToken: String?,
+        presentationId: String?,
     ): PurchaseResolution {
         if (!active.connect()) {
             return PurchaseResolution.Failed("PLAY_BILLING_SERVICE_UNAVAILABLE", UNAVAILABLE_MESSAGE)
@@ -197,6 +323,12 @@ class CapacitorPlayBillingPlugin : Plugin() {
         // the owned purchase; the 0.3 contract rejects instead, and the owned
         // purchase still reaches JavaScript through `purchaseUpdated`.
         val ownedBefore = active.inAppPurchases().mapNotNullTo(HashSet()) { it.purchaseToken }
+        // A flow the call timeout already ended must not open a sheet now.
+        currentCoroutineContext().ensureActive()
+        if (presentationId != null && !presentation.isTracking(presentationId)) {
+            return PurchaseResolution.Failed("PLAY_BILLING_TIMEOUT", "Purchase confirmation timed out; requery owned purchases.")
+        }
+        presentationId?.let { presentation.onLaunchAttempted(it) }
         val (purchases, error) = active.purchase(activity, productId, offer.offerTokenAndroid.orEmpty(), accountId)
         val matched = purchases.firstOrNull { it.ids.orEmpty().contains(productId) }
         if (matched != null) {
@@ -214,13 +346,22 @@ class CapacitorPlayBillingPlugin : Plugin() {
         }
     }
 
-    private fun settlePurchase(call: PluginCall, productId: String, resolution: PurchaseResolution) {
+    private fun settlePurchase(
+        call: PluginCall,
+        productId: String,
+        presentationId: String?,
+        resolution: PurchaseResolution,
+    ) {
         if (activePurchase === call) {
             clearActivePurchase(call)
+            // The answer carries the sheet state too, so the SDK reads a
+            // `not-started` or `closed` that the event may not have delivered
+            // yet. `open` means the sheet is still up and `closed` follows.
+            val sheet = presentationId?.let { presentation.answerState(it) }
             when (resolution) {
-                is PurchaseResolution.Reported -> call.resolve(toJs(resolution.outcome))
-                PurchaseResolution.Cancelled -> call.resolve(JSObject().put("status", "cancelled"))
-                is PurchaseResolution.Failed -> call.reject(resolution.message, resolution.code)
+                is PurchaseResolution.Reported -> call.resolve(withPresentation(toJs(resolution.outcome), sheet))
+                PurchaseResolution.Cancelled -> call.resolve(withPresentation(JSObject().put("status", "cancelled"), sheet))
+                is PurchaseResolution.Failed -> call.reject(resolution.message, resolution.code, null, presentationData(presentationId))
             }
             return
         }
@@ -282,6 +423,54 @@ class CapacitorPlayBillingPlugin : Plugin() {
         notifyListeners("purchaseUpdated", outcome, true)
     }
 
+    /**
+     * Bounds how long one sheet keeps the plugin busy without the host
+     * resuming; the TypeScript provider has the same bound for the game.
+     */
+    private fun armSheetTimeout(id: String) {
+        sheetTimeout?.cancel()
+        sheetTimeout = scope.launch {
+            delay(SHEET_TIMEOUT_MILLIS)
+            presentation.onSafetyTimeout(id)
+        }
+    }
+
+    private fun armLateLaunchBound(id: String) {
+        lateLaunchBound?.cancel()
+        lateLaunchBound = scope.launch {
+            delay(LATE_LAUNCH_BOUND_MILLIS)
+            presentation.onLateBound(id)
+        }
+    }
+
+    /** A refusal before any flow began; its sheet never opened. */
+    private fun rejectNotStarted(call: PluginCall, id: String?, message: String, code: String) {
+        if (id == null) {
+            call.reject(message, code)
+            return
+        }
+        notifyPresentation(id, PurchasePresentationTracker.NOT_STARTED, null)
+        call.reject(message, code, null, JSObject().put("presentation", PurchasePresentationTracker.NOT_STARTED))
+    }
+
+    private fun presentationData(id: String?): JSObject? =
+        id?.let { JSObject().put("presentation", presentation.answerState(it)) }
+
+    private fun withPresentation(answer: JSObject, sheet: String?): JSObject =
+        if (sheet == null) answer else answer.put("presentation", sheet)
+
+    /**
+     * Retained until a listener consumes it, like `purchaseUpdated`; the
+     * random id keeps a fact of an earlier web session from matching a new call.
+     */
+    private fun notifyPresentation(id: String, state: String, reason: String?) {
+        val event = JSObject().put("presentationId", id).put("state", state)
+        if (reason != null) {
+            event.put("reason", reason)
+        }
+        notifyListeners("purchasePresentation", event, true)
+    }
+
     private fun connectionOrReject(call: PluginCall): OpenIapPlayConnection? {
         connection?.let { return it }
         call.reject(providerError ?: "Google Play Billing is not configured.", "PLAY_BILLING_CONFIGURATION_ERROR")
@@ -321,6 +510,7 @@ class CapacitorPlayBillingPlugin : Plugin() {
         if (activePurchase === call) {
             activePurchase = null
             activeProductId = null
+            presentationId = null
             purchaseTimeout?.cancel()
             purchaseTimeout = null
         }
@@ -343,6 +533,12 @@ class CapacitorPlayBillingPlugin : Plugin() {
     private companion object {
         const val TAG = "CapacitorPlayBilling"
         const val PURCHASE_TIMEOUT_MILLIS = 180_000L
+        /** How long a launched flow waits for its billing activity before it counts as never shown. */
+        const val LAUNCH_OBSERVATION_GRACE_MILLIS = 500L
+        /** How long a launched flow's verdict may wait for the game's paused activity. */
+        const val LATE_LAUNCH_BOUND_MILLIS = 10_000L
+        /** The OpenIAP Google purchase flow timeout, and the TypeScript provider's sheet bound. */
+        const val SHEET_TIMEOUT_MILLIS = 900_000L
         const val UNAVAILABLE_MESSAGE = "Google Play Billing is unavailable."
         const val EMPTY_MESSAGE = "Purchase callback was empty; requery owned purchases."
 

package/android/src/main/java/dev/mpgd/capacitor/playbilling/PurchasePresentationTracker.kt

@@ -0,0 +1,210 @@
+package dev.mpgd.capacitor.playbilling
+
+/**
+ * Sheet facts for one Play purchase flow at a time, from activity lifecycle
+ * observations only, never from a purchase result:
+ *
+ * - `open` when a Billing Library activity
+ *   (`com.android.billingclient.api.ProxyBillingActivity` or `...V2`, the
+ *   translucent activity `launchBillingFlow` starts in this process once it
+ *   returns OK) is created during the flow, however late;
+ * - `closed` when an activity of the app that is not a billing activity
+ *   resumes after that: the host sits below the billing activities in the
+ *   same task, so it resumes only once the Play sheet is gone;
+ * - `not-started` when the flow ended without a billing activity: a refusal
+ *   before the launch, or a launch that brought nothing over the game. After
+ *   a launch attempt the verdict waits while the game's activity is paused
+ *   (something is coming over it, a billing activity that is slow to be
+ *   created included) until it resumes, a billing activity appears, or the
+ *   plugin's bound passes.
+ *
+ * `onPurchasesUpdated`, a pending purchase, or the plugin's call timeout are
+ * not observations of the sheet. Every `open` is followed by exactly one
+ * `closed`: the activity that resumes, teardown (`interrupted`), or the
+ * plugin's safety bound (`timeout`). The flow stays [active] (the plugin
+ * answers `PLAY_BILLING_BUSY`) until its terminal fact. Pure Kotlin, driven
+ * on the main thread by the plugin, so the JVM tests can run it.
+ */
+internal class PurchasePresentationTracker(
+    private val emit: (presentationId: String, state: String, reason: String?) -> Unit,
+) {
+    private enum class State { REQUESTED, OPEN }
+
+    private var presentationId: String? = null
+    private var state = State.REQUESTED
+    private var launchAttempted = false
+    private var flowEnded = false
+
+    /** A non-billing activity paused after the launch attempt, with no billing activity seen yet. */
+    private var hostPaused = false
+
+    /** The last fact of the flow that has ended, for its call's answer. */
+    private var lastFact: Pair<String, String>? = null
+
+    val active: Boolean get() = presentationId != null
+
+    /** The id of the flow whose sheet is open now, if any. */
+    val openPresentationId: String? get() = if (state == State.OPEN) presentationId else null
+
+    fun begin(id: String) {
+        presentationId = id
+        state = State.REQUESTED
+        launchAttempted = false
+        flowEnded = false
+        hostPaused = false
+        lastFact = null
+    }
+
+    /** Whether [id] is the flow being tracked; a flow ended early must not launch. */
+    fun isTracking(id: String): Boolean = presentationId == id
+
+    /** The flow of [id] is about to call `launchBillingFlow` (through OpenIAP). */
+    fun onLaunchAttempted(id: String) {
+        if (presentationId == id) {
+            launchAttempted = true
+        }
+    }
+
+    fun onActivityCreated(className: String) {
+        val id = presentationId ?: return
+        if (state == State.REQUESTED && isBillingActivity(className)) {
+            state = State.OPEN
+            hostPaused = false
+            emit(id, OPEN, null)
+        }
+    }
+
+    fun onActivityPaused(className: String) {
+        if (presentationId != null && state == State.REQUESTED && launchAttempted &&
+            !isBillingActivity(className)
+        ) {
+            hostPaused = true
+        }
+    }
+
+    fun onActivityResumed(className: String) {
+        if (presentationId == null || isBillingActivity(className)) return
+        if (state == State.OPEN) {
+            end(CLOSED, null)
+            return
+        }
+        // Back without a billing activity: whatever covered the game was not
+        // the sheet. An ended flow is decided now.
+        hostPaused = false
+        if (flowEnded) {
+            end(NOT_STARTED, null)
+        }
+    }
+
+    /**
+     * True while a launch was attempted, the flow is still running, and no
+     * billing activity was seen: the activity `launchBillingFlow` started may
+     * not be created yet (the game's activity may not even be paused yet), so
+     * the plugin waits briefly before it ends the flow.
+     */
+    fun awaitsLaunchObservation(id: String): Boolean =
+        presentationId == id && state == State.REQUESTED && launchAttempted && !flowEnded
+
+    /**
+     * The OpenIAP flow of [id] returned (or never started). Decides
+     * `not-started` when nothing opened, unless a launch was attempted and
+     * the game's activity is still paused: then the verdict waits for it to
+     * resume (`not-started`), a billing activity (`open`), or [onLateBound].
+     */
+    fun onFlowEnded(id: String) {
+        if (presentationId != id || state != State.REQUESTED) return
+        flowEnded = true
+        if (!launchAttempted || !hostPaused) {
+            end(NOT_STARTED, null)
+        }
+    }
+
+    /** The plugin's bound on a deferred verdict passed: nothing opened. */
+    fun onLateBound(id: String) {
+        if (presentationId == id && state == State.REQUESTED && flowEnded) {
+            end(NOT_STARTED, null)
+        }
+    }
+
+    /**
+     * The plugin's call timeout for [id] before `launchBillingFlow` was ever
+     * called: the flow is ended `not-started` (the plugin cancels it, and a
+     * flow no longer tracked never launches). True when it ended the flow.
+     */
+    fun cancelBeforeLaunch(id: String): Boolean {
+        if (presentationId != id || state != State.REQUESTED || launchAttempted) return false
+        end(NOT_STARTED, null)
+        return true
+    }
+
+    /**
+     * The sheet of [id] stayed open past the plugin's safety bound without the
+     * host resuming: report it closed (`timeout`) so a new flow can start.
+     */
+    fun onSafetyTimeout(id: String) {
+        if (presentationId == id && state == State.OPEN) {
+            end(CLOSED, TIMEOUT)
+        }
+    }
+
+    /**
+     * The plugin is torn down: nothing will be observed any more. When the
+     * activity is only recreated ([reportClosed] false, a configuration
+     * change), the sheet may still be up, so no `closed` is claimed: the
+     * flow is forgotten and the TypeScript provider's safety timeout ends it
+     * for a web view that survives.
+     */
+    fun onTeardown(reportClosed: Boolean = true) {
+        if (presentationId == null) return
+        if (!reportClosed) {
+            presentationId = null
+            return
+        }
+        if (state == State.OPEN || launchAttempted) {
+            end(CLOSED, INTERRUPTED)
+        } else {
+            end(NOT_STARTED, null)
+        }
+    }
+
+    /**
+     * What the call's answer reports for [id]: `open` or `closed` or
+     * `not-started` for the current or just ended flow, and `requested` while
+     * the flow runs without a verdict yet (facts follow as events).
+     */
+    fun answerState(id: String): String {
+        if (presentationId == id) {
+            return if (state == State.OPEN) OPEN else REQUESTED_STATE
+        }
+        val last = lastFact
+        return if (last != null && last.first == id) last.second else REQUESTED_STATE
+    }
+
+    private fun end(fact: String, reason: String?) {
+        val id = presentationId ?: return
+        presentationId = null
+        lastFact = id to fact
+        emit(id, fact, reason)
+    }
+
+    companion object {
+        const val OPEN = "open"
+        const val CLOSED = "closed"
+        const val NOT_STARTED = "not-started"
+        const val REQUESTED_STATE = "requested"
+        const val INTERRUPTED = "interrupted"
+        const val TIMEOUT = "timeout"
+
+        /** The protocol version `getPresentationSupport` declares. */
+        const val PROTOCOL_VERSION = 1
+
+        private const val BILLING_ACTIVITY_PREFIX = "com.android.billingclient."
+        private val presentationIdPattern = Regex("^[A-Za-z0-9-]{1,64}$")
+
+        fun isBillingActivity(className: String): Boolean =
+            className.startsWith(BILLING_ACTIVITY_PREFIX)
+
+        fun isValidPresentationId(value: String?): Boolean =
+            value != null && presentationIdPattern.matches(value)
+    }
+}

package/dist/commerce-provider.d.ts

@@ -47,6 +47,15 @@ export interface CreateCapacitorPlayBillingCommerceProviderInput {
   readonly mapError?: StoreSdkErrorCodeMap;
   /** Diagnostics for a retired SKU or a multi-line purchase. The purchase is still surfaced; see the SDK input. */
   readonly onUnmappedPurchase?: (purchase: PlayPurchase) => void;
+  /**
+  * Play sheet facts (default true): the provider offers `presentation`,
+  * observed from the activity lifecycle, so the gateway and the game
+  * runtime pause until the Play sheet is gone, not until a result. Needs an
+  * app built with this package's native code (otherwise new purchases are
+  * refused with `PLAY_BILLING_PRESENTATION_UNSUPPORTED`). False keeps the
+  * result-based pause of earlier releases.
+  */
+  readonly purchasePresentation?: boolean;
 }
 /**
 * Commerce v2 `CommerceProvider` for Google Play: `createStoreCommerceProvider`

package/dist/commerce-provider.js

@@ -43,6 +43,9 @@ export function createCapacitorPlayBillingCommerceProvider(input) {
         ...(input.onUnmappedPurchase === undefined
             ? {}
             : { onUnmappedPurchase: input.onUnmappedPurchase }),
+        ...(input.purchasePresentation === undefined
+            ? {}
+            : { purchasePresentation: input.purchasePresentation }),
     });
     const resolveAccountBinding = input.accountBinding;
     const gate = resolvePurchaseGateSupport(input.purchaseGate);

package/dist/definitions.d.ts

@@ -55,6 +55,33 @@ export interface PlayPurchaseOutcome {
   readonly productId?: string;
   /** The `PLAY_BILLING_*` code of a late `failed` result. */
   readonly code?: string;
+  /**
+  * The Play sheet when a `purchase` call with a `presentationId` answered
+  * (also in a rejection's `data`): `open` (still up; `closed` follows as a
+  * `purchasePresentation` event), `closed`, `not-started`, or `requested`
+  * (no fact yet; facts follow as events).
+  */
+  readonly presentation?: PlayPurchaseAnswerPresentation;
+}
+export type PlayPurchasePresentationState = 'open' | 'closed' | 'not-started';
+export type PlayPurchaseAnswerPresentation = PlayPurchasePresentationState | 'requested';
+/**
+* A Play sheet fact for the `purchase` call that sent `presentationId`,
+* observed from the activity lifecycle and never from a purchase result:
+* `open` once the Billing Library's activity is created, `closed` when the
+* game's activity resumes after it (reason `interrupted` when the plugin was
+* torn down, `timeout` past its 15-minute bound), `not-started` when the flow
+* ended without it.
+*/
+export interface PlayPurchasePresentationEvent {
+  readonly presentationId: string;
+  readonly state: PlayPurchasePresentationState;
+  /** Teardown, or the plugin's 15-minute bound on one sheet without the game's activity resuming. */
+  readonly reason?: 'interrupted' | 'timeout';
+}
+/** What `getPresentationSupport` declares; `purchasePresentation` is the facts protocol version. */
+export interface PlayPresentationSupport {
+  readonly purchasePresentation: number;
 }
 export interface CapacitorPlayBillingPlugin {
   getProducts(input: {
@@ -66,8 +93,16 @@ export interface CapacitorPlayBillingPlugin {
     readonly productId: string;
     readonly offerToken?: string;
     readonly obfuscatedAccountId: string;
+    /** Asks for this call's sheet facts (`purchasePresentation`); 1-64 of `[A-Za-z0-9-]`. */
+    readonly presentationId?: string;
   }): Promise<PlayPurchaseOutcome>;
   /**
+  * Declares the sheet facts the native code reports. A native build from
+  * before them answers `UNIMPLEMENTED`; optional so a plugin double without
+  * it still type-checks, and then the SDK refuses purchases that need facts.
+  */
+  getPresentationSupport?(): Promise<PlayPresentationSupport>;
+  /**
   * Requeries every purchased or pending in-app purchase Play still reports
   * for this user and device (`queryPurchasesAsync`): unconsumed consumables,
   * acknowledged and unacknowledged durables, and pending purchases. The
@@ -83,4 +118,6 @@ export interface CapacitorPlayBillingPlugin {
   * until the first listener consumes them.
   */
   addListener(eventName: 'purchaseUpdated', listener: (event: PlayPurchaseOutcome) => void): Promise<PluginListenerHandle>;
+  /** Sheet facts of `purchase` calls that sent a `presentationId`; retained until a listener attaches. */
+  addListener(eventName: 'purchasePresentation', listener: (event: PlayPurchasePresentationEvent) => void): Promise<PluginListenerHandle>;
 }

package/dist/purchase-presentation.d.ts

@@ -0,0 +1,27 @@
+import type { PluginListenerHandle } from '@capacitor/core';
+export type PlayBillingPurchasePresentationState = 'open' | 'closed' | 'not-started' | 'unknown';
+/** A sheet fact of one `requestPurchase` call; see `StoreSdkPurchasePresentationEvent`. */
+export interface PlayBillingSdkPurchasePresentationEvent {
+  readonly presentationId: string;
+  readonly state: PlayBillingPurchasePresentationState;
+  readonly reason?: 'interrupted' | 'timeout';
+}
+/** The SDK's `purchasePresentation`; see `StoreSdkPurchasePresentation` in `@mpgd/adapter-capacitor`. */
+export interface PlayBillingSdkPurchasePresentation {
+  subscribe(listener: (event: PlayBillingSdkPurchasePresentationEvent) => void): () => void;
+}
+/** See `NativePurchasePresentation` in `@mpgd/adapter-capacitor`. */
+export interface PlayBillingNativePurchasePresentation {
+  readonly purchasePresentation: PlayBillingSdkPurchasePresentation;
+  supported(): Promise<boolean>;
+  followed(): boolean;
+  begin(presentationId: string): void;
+  answered(presentationId: string, answerOrError: unknown): void;
+}
+/** The native surface the facts need: the plugin's event and support check. */
+export interface PlayBillingNativePresentationPlugin {
+  addListener(eventName: 'purchasePresentation', listener: (event: unknown) => void): Promise<PluginListenerHandle>;
+  readonly getPresentationSupport?: () => Promise<unknown>;
+}
+/** The adapter's facts helper over `native`, or undefined with an adapter from before it. */
+export declare function resolvePlayBillingNativePurchasePresentation(native: PlayBillingNativePresentationPlugin, adapterExports?: object): PlayBillingNativePurchasePresentation | undefined;

package/dist/purchase-presentation.js

@@ -0,0 +1,9 @@
+import * as adapterCapacitor from '@mpgd/adapter-capacitor';
+/** The adapter's facts helper over `native`, or undefined with an adapter from before it. */
+export function resolvePlayBillingNativePurchasePresentation(native, adapterExports = adapterCapacitor) {
+    const factory = adapterExports.createNativePurchasePresentation;
+    if (typeof factory !== 'function') {
+        return undefined;
+    }
+    return factory(native);
+}

package/dist/store-sdk.d.ts

@@ -2,12 +2,22 @@ import type { PlatformProviderAvailability } from '@mpgd/platform';
 import { type StoreSdk, type StoreSdkError, type StoreSdkErrorCodeMap, type StoreSdkPurchase } from '@mpgd/adapter-capacitor';
 import type { CapacitorPlayBillingPlugin, PlayPurchase } from './definitions.js';
 import { googlePlayStoreId, playBillingStoreSdkCapabilities } from './commerce-profile.js';
+import { type PlayBillingSdkPurchasePresentation } from './purchase-presentation.js';
+export type { PlayBillingPurchasePresentationState, PlayBillingSdkPurchasePresentation, PlayBillingSdkPurchasePresentationEvent, } from './purchase-presentation.js';
 export { googlePlayStoreId, playBillingStoreSdkCapabilities };
 /**
 * `defaultStoreSdkErrorCodeMap` plus every `PLAY_BILLING_*` code the plugin or
 * this SDK emits that the default map does not already normalize.
 */
 export declare const playBillingStoreSdkErrorCodeMap: StoreSdkErrorCodeMap;
+/**
+* The code of a purchase refused because the native plugin in the app binary
+* reports no sheet facts (a web bundle newer than its native build). The
+* provider offers `presentation`, so a purchase it could not follow is not
+* sold; rebuilding the app with this package's native code, or
+* `purchasePresentation: false`, sells again. Recovery is unaffected.
+*/
+export declare const playBillingPresentationUnsupportedCode: 'PLAY_BILLING_PRESENTATION_UNSUPPORTED';
 /** One Play product the SDK sells; the provider maps it to a logical id. */
 export interface PlayBillingStoreSdkProduct {
   /** The Play product id (SKU). */
@@ -35,10 +45,20 @@ export interface CreateCapacitorPlayBillingStoreSdkInput {
   * acknowledge one without a logical product id.
   */
   readonly onUnmappedPurchase?: (purchase: PlayPurchase) => void;
+  /**
+  * Report the Play sheet's facts (`purchasePresentation`), so the adapter's
+  * provider offers `CommerceProvider.presentation` and the game pauses until
+  * the sheet is gone rather than until a result. Defaults to true. A native
+  * build without the facts then refuses new purchases with
+  * `PLAY_BILLING_PRESENTATION_UNSUPPORTED`; false keeps the result-based
+  * pause of earlier releases.
+  */
+  readonly purchasePresentation?: boolean;
 }
 export interface CapacitorPlayBillingStoreSdk extends StoreSdk {
   readonly store: typeof googlePlayStoreId;
   getAvailability(): Promise<PlatformProviderAvailability>;
+  readonly purchasePresentation?: PlayBillingSdkPurchasePresentation;
 }
 interface PlayBillingStoreSdkErrorOptions {
   readonly retryable?: boolean;

package/dist/store-sdk.js

@@ -3,6 +3,7 @@ import { defaultStoreSdkErrorCodeMap, } from '@mpgd/adapter-capacitor';
 import { createGooglePlayTokenPurchaseKey } from '@mpgd/platform/commerce';
 import { googlePlayStoreId, playBillingStoreSdkCapabilities } from './commerce-profile.js';
 import { CapacitorPlayBilling } from './plugin.js';
+import { resolvePlayBillingNativePurchasePresentation, } from './purchase-presentation.js';
 // The profile constants live in the SDK-free `commerce-profile.ts` so a tools
 // project can read them without loading Capacitor; they stay exported here.
 export { googlePlayStoreId, playBillingStoreSdkCapabilities };
@@ -19,8 +20,17 @@ export const playBillingStoreSdkErrorCodeMap = Object.freeze({
     PLAY_BILLING_INVALID_REQUEST: 'CONFIGURATION_REQUIRED',
     PLAY_BILLING_ACTIVITY_REQUIRED: 'NOT_PREPARED',
     PLAY_BILLING_ANDROID_REQUIRED: 'STORE_UNAVAILABLE',
+    PLAY_BILLING_PRESENTATION_UNSUPPORTED: 'CONFIGURATION_REQUIRED',
     PLAY_BILLING_ERROR: 'UNKNOWN',
 });
+/**
+ * The code of a purchase refused because the native plugin in the app binary
+ * reports no sheet facts (a web bundle newer than its native build). The
+ * provider offers `presentation`, so a purchase it could not follow is not
+ * sold; rebuilding the app with this package's native code, or
+ * `purchasePresentation: false`, sells again. Recovery is unaffected.
+ */
+export const playBillingPresentationUnsupportedCode = 'PLAY_BILLING_PRESENTATION_UNSUPPORTED';
 const productIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
 const obfuscatedAccountIdPattern = /^[A-Za-z0-9._-]{1,64}$/u;
 const maximumProducts = 100;
@@ -261,9 +271,14 @@ export function createCapacitorPlayBillingStoreSdk(input) {
         pluginListenerGeneration += 1;
         handle.then((resolved) => resolved.remove()).catch(() => undefined);
     };
+    // Sheet facts of `purchase` calls that carry a presentation id.
+    const presentation = input.purchasePresentation === false
+        ? undefined
+        : resolvePlayBillingNativePurchasePresentation(plugin);
     const sdk = {
         store: googlePlayStoreId,
         capabilities: playBillingStoreSdkCapabilities,
+        ...(presentation === undefined ? {} : { purchasePresentation: presentation.purchasePresentation }),
         async fetchProducts(request) {
             assertAndroid(isAndroid);
             if (request.type === 'subscription') {
@@ -322,17 +337,34 @@ export function createCapacitorPlayBillingStoreSdk(input) {
                 throw new PlayBillingStoreSdkError('PLAY_BILLING_ACCOUNT_REQUIRED', 'Play Billing requires an obfuscated account id that agrees with the backend resolver.');
             }
             const offerToken = request.offerId ?? product.offerToken;
+            // Only an adapter that reads sheet facts sends an id (one from before
+            // them never does, and the purchase runs as in earlier releases).
+            const presentationId = presentation === undefined ? undefined : request.presentationId;
+            if (presentation !== undefined && presentationId !== undefined) {
+                if (!(await presentation.supported())) {
+                    throw new PlayBillingStoreSdkError(playBillingPresentationUnsupportedCode, 'The app was built with a Play Billing plugin that reports no purchase sheet facts; '
+                        + "rebuild it with this package's native code.", { retryable: false });
+                }
+                presentation.begin(presentationId);
+            }
             let outcome;
             try {
                 outcome = await plugin.purchase({
                     productId: product.sku,
                     obfuscatedAccountId: binding.value,
                     ...(offerToken === undefined ? {} : { offerToken }),
+                    ...(presentationId === undefined ? {} : { presentationId }),
                 });
             }
             catch (error) {
+                if (presentationId !== undefined) {
+                    presentation?.answered(presentationId, error);
+                }
                 return { outcome: 'failed', error: toSdkError(error) };
             }
+            if (presentationId !== undefined) {
+                presentation?.answered(presentationId, outcome);
+            }
             if (!isRecord(outcome)) {
                 throw invalidResponse('Play returned an invalid purchase outcome.');
             }
@@ -396,6 +428,12 @@ export function createCapacitorPlayBillingStoreSdk(input) {
             if (!isAndroid()) {
                 return 'unsupported';
             }
+            // An adapter that reads sheet facts over a native build without them
+            // would refuse every purchase: report the store as needing a rebuild,
+            // so the shop sells nothing and no idempotency key is spent.
+            if (presentation !== undefined && presentation.followed() && !(await presentation.supported())) {
+                return 'configuration-required';
+            }
             try {
                 const response = await plugin.getProducts({ productIds: [...products.keys()] });
                 const purchasable = readArray(response, 'products').some((found) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mpgd/capacitor-play-billing",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Opt-in Android Google Play Billing purchase collector for mpgd Capacitor games.",
   "license": "MIT",
   "repository": {
@@ -38,9 +38,9 @@
   ],
   "peerDependencies": {
     "@capacitor/core": "^8.5.1",
-    "@mpgd/adapter-capacitor": "^0.17.0",
-    "@mpgd/bridge": "^0.17.0",
-    "@mpgd/platform": "^0.33.0"
+    "@mpgd/adapter-capacitor": "^0.18.0",
+    "@mpgd/bridge": "^0.18.0",
+    "@mpgd/platform": "^0.34.0"
   },
   "devDependencies": {
     "@capacitor/core": "8.5.2",
@@ -48,10 +48,10 @@
     "ttsc": "0.34.2",
     "typescript": "7.0.2",
     "vitest": "^4.0.0",
-    "@mpgd/adapter-capacitor": "0.17.0",
-    "@mpgd/bridge": "0.17.0",
-    "@mpgd/platform": "0.33.0",
-    "@mpgd/game-services": "0.31.0"
+    "@mpgd/adapter-capacitor": "0.18.0",
+    "@mpgd/bridge": "0.18.0",
+    "@mpgd/platform": "0.34.0",
+    "@mpgd/game-services": "0.32.0"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",