Wire PaywallOptions web view message handler through paywall state.

AlvaroBrey · JZDesign · commit 8d106921acb2 · 2026-07-10T11:30:26.000-05:00
diff --git a/ui/revenuecatui/api.txt b/ui/revenuecatui/api.txt
@@ -96,11 +96,13 @@ package com.revenuecat.purchases.ui.revenuecatui {
     method public com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider? getFontProvider();
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallListener? getListener();
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic? getPurchaseLogic();
+    method public com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler? getWebViewMessageHandler();
     property public final java.util.Map<java.lang.String,com.revenuecat.purchases.ui.revenuecatui.CustomVariableValue> customVariables;
     property public final kotlin.jvm.functions.Function0<kotlin.Unit> dismissRequest;
     property public final com.revenuecat.purchases.ui.revenuecatui.fonts.FontProvider? fontProvider;
     property public final com.revenuecat.purchases.ui.revenuecatui.PaywallListener? listener;
     property public final com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic? purchaseLogic;
+    property public final com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler? webViewMessageHandler;
     field public static final com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Companion Companion;
   }
 
@@ -113,6 +115,7 @@ package com.revenuecat.purchases.ui.revenuecatui {
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Builder setOffering(com.revenuecat.purchases.Offering? offering);
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Builder setPurchaseLogic(com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic? purchaseLogic);
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Builder setShouldDisplayDismissButton(boolean shouldDisplayDismissButton);
+    method public com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Builder setWebViewMessageHandler(com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler? handler);
   }
 
   public static final class PaywallOptions.Companion {
diff --git a/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallOptions.kt b/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallOptions.kt
@@ -60,6 +60,11 @@ public class PaywallOptions internal constructor(
      * `{{ $custom.key }}` placeholders in the paywall configuration.
      */
     public val customVariables: Map<String, CustomVariableValue> = emptyMap(),
+    /**
+     * Handler for messages sent by Paywalls V2 `web_view` components. Lets app code receive validated
+     * messages and reply to them. See [PaywallWebViewMessageHandler].
+     */
+    public val webViewMessageHandler: PaywallWebViewMessageHandler? = null,
     internal val injectedWorkflow: PublishedWorkflow? = null,
     internal val injectedWorkflowUiConfig: UiConfig = emptyUiConfig(),
 ) {
@@ -77,6 +82,7 @@ public class PaywallOptions internal constructor(
         dismissRequest = builder.dismissRequest,
         dismissRequestWithExitOffering = builder.dismissRequestWithExitOffering,
         customVariables = builder.customVariables,
+        webViewMessageHandler = builder.webViewMessageHandler,
         injectedWorkflow = builder.injectedWorkflow,
         injectedWorkflowUiConfig = builder.injectedWorkflowUiConfig,
     )
@@ -106,6 +112,7 @@ public class PaywallOptions internal constructor(
             this.purchaseLogic != other.purchaseLogic -> false
             this.mode != other.mode -> false
             this.customVariables != other.customVariables -> false
+            this.webViewMessageHandler != other.webViewMessageHandler -> false
             this.injectedWorkflow != other.injectedWorkflow -> false
             this.injectedWorkflowUiConfig != other.injectedWorkflowUiConfig -> false
             else -> this.dismissRequest == other.dismissRequest
@@ -122,6 +129,7 @@ public class PaywallOptions internal constructor(
         dismissRequest: () -> Unit = this.dismissRequest,
         dismissRequestWithExitOffering: ((Offering?, PaywallResult?) -> Unit)? = this.dismissRequestWithExitOffering,
         customVariables: Map<String, CustomVariableValue> = this.customVariables,
+        webViewMessageHandler: PaywallWebViewMessageHandler? = this.webViewMessageHandler,
         injectedWorkflow: PublishedWorkflow? = this.injectedWorkflow,
         injectedWorkflowUiConfig: UiConfig = this.injectedWorkflowUiConfig,
     ): PaywallOptions = PaywallOptions(
@@ -134,6 +142,7 @@ public class PaywallOptions internal constructor(
         dismissRequest = dismissRequest,
         dismissRequestWithExitOffering = dismissRequestWithExitOffering,
         customVariables = customVariables,
+        webViewMessageHandler = webViewMessageHandler,
         injectedWorkflow = injectedWorkflow,
         injectedWorkflowUiConfig = injectedWorkflowUiConfig,
     )
@@ -150,6 +159,7 @@ public class PaywallOptions internal constructor(
         internal var mode: PaywallMode = PaywallMode.default
         internal var dismissRequestWithExitOffering: ((Offering?, PaywallResult?) -> Unit)? = null
         internal var customVariables: Map<String, CustomVariableValue> = emptyMap()
+        internal var webViewMessageHandler: PaywallWebViewMessageHandler? = null
         internal var injectedWorkflow: PublishedWorkflow? = null
         internal var injectedWorkflowUiConfig: UiConfig = emptyUiConfig()
 
@@ -213,6 +223,19 @@ public class PaywallOptions internal constructor(
             this.customVariables = CustomVariableKeyValidator.validateAndFilter(variables)
         }
 
+        /**
+         * Sets a handler for messages sent by Paywalls V2 `web_view` components. The handler receives
+         * validated messages (such as `rc:step-complete`, `rc:request-variables`, and `rc:error`) on
+         * the main thread, along with a [PaywallWebViewController] for replying to the web view.
+         *
+         * Bidirectional messaging is always enabled for `web_view` components; this handler is how the
+         * app observes and responds to those messages. The SDK does not automatically dismiss the
+         * paywall or trigger a purchase in response to any message.
+         */
+        public fun setWebViewMessageHandler(handler: PaywallWebViewMessageHandler?): Builder = apply {
+            this.webViewMessageHandler = handler
+        }
+
         /**
          * Injects a pre-built workflow (multipage paywall) to render locally without fetching
          * it from the backend, together with the [Offering] it renders against. Internal
diff --git a/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/webview/WebViewComponentView.kt b/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/webview/WebViewComponentView.kt
@@ -48,6 +48,7 @@ internal fun WebViewComponentView(
 
     val componentId = style.componentId
     val locale = state.locale.toLanguageTag()
+    val messageHandler = state.webViewMessageHandler
     val sizeToContentWidth = style.size.width is Fit
     val sizeToContentHeight = style.size.height is Fit
 
@@ -86,7 +87,7 @@ internal fun WebViewComponentView(
                             componentId = id,
                             expectedUrl = resolvedUrl,
                             locale = locale,
-                            messageHandler = null,
+                            messageHandler = messageHandler,
                             protocolVersion = style.protocolVersion ?: WebViewEnvelope.DEFAULT_PROTOCOL_VERSION,
                             sizeToContentWidth = sizeToContentWidth,
                             sizeToContentHeight = sizeToContentHeight,
@@ -104,7 +105,10 @@ internal fun WebViewComponentView(
                 }
             },
             update = {
-                bridgeHolder.bridge?.update(locale = locale, messageHandler = null)
+                bridgeHolder.bridge?.update(
+                    locale = locale,
+                    messageHandler = messageHandler,
+                )
             },
             onRelease = { webView ->
                 bridgeHolder.bridge?.release()
diff --git a/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallState.kt b/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallState.kt
@@ -17,6 +17,7 @@ import com.revenuecat.purchases.Package
 import com.revenuecat.purchases.UiConfig.VariableConfig
 import com.revenuecat.purchases.paywalls.components.common.LocaleId
 import com.revenuecat.purchases.ui.revenuecatui.CustomVariableValue
+import com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.getBestMatch
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.toComposeLocale
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.toJavaLocale
@@ -85,7 +86,7 @@ internal sealed interface PaywallState {
             }
         }
 
-        @Suppress("LongParameterList")
+        @Suppress("LongParameterList", "TooManyFunctions")
         @Stable
         class Components(
             val stack: ComponentStyle,
@@ -116,6 +117,7 @@ internal sealed interface PaywallState {
              * Default custom variables from the dashboard configuration.
              */
             val defaultCustomVariables: Map<String, CustomVariableValue> = emptyMap(),
+            initialWebViewMessageHandler: PaywallWebViewMessageHandler? = null,
             initialLocaleList: LocaleList = LocaleList.current,
             initialSelectedTabIndex: Int? = null,
             initialSheetState: SimpleSheetState = SimpleSheetState(),
@@ -188,6 +190,17 @@ internal sealed interface PaywallState {
 
             private var localeId by mutableStateOf(initialLocaleList.toLocaleId())
 
+            /**
+             * Optional handler for messages sent by `web_view` components, set via
+             * [com.revenuecat.purchases.ui.revenuecatui.PaywallOptions.Builder.setWebViewMessageHandler].
+             *
+             * Backed by snapshot state and refreshed in place (without rebuilding the paywall state) when
+             * the handler changes on [com.revenuecat.purchases.ui.revenuecatui.PaywallOptions]; see
+             * `PaywallViewModelImpl.updateOptions`.
+             */
+            var webViewMessageHandler by mutableStateOf(initialWebViewMessageHandler)
+                private set
+
             // We find all available device locales with the same country as the storefront country.
             private val availableStorefrontCountryLocalesByLanguage: Map<String, Locale> by lazy {
                 if (storefrontCountryCode.isNullOrBlank()) {
@@ -342,6 +355,10 @@ internal sealed interface PaywallState {
                 if (actionInProgress != null) this.actionInProgress = actionInProgress
             }
 
+            fun update(webViewMessageHandler: PaywallWebViewMessageHandler?) {
+                this.webViewMessageHandler = webViewMessageHandler
+            }
+
             fun update(selectedPackageUniqueId: String) {
                 this.selectedPackageUniqueId = selectedPackageUniqueId
 
diff --git a/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModel.kt b/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModel.kt
@@ -275,9 +275,22 @@ internal class PaywallViewModelImpl(
         val needsUpdateState = this.options.hashCode() != options.hashCode()
         // Some properties not considered for equality (hashCode) may have changed
         // (e.g. the listener may change in some re-renderers)
+        val previousWebViewMessageHandler = this.options.webViewMessageHandler
         this.options = options
         if (needsUpdateState) {
             updateState()
+        } else if (previousWebViewMessageHandler !== options.webViewMessageHandler) {
+            // The web view message handler is excluded from hashCode and is baked into the loaded
+            // Components state, so a handler-only change won't rebuild state. Refresh it in place
+            // (like refreshStateIfLocaleChanged) so web_view components get the latest handler without
+            // re-resolving the offering or resetting selections.
+            val currentState = _state.value
+            if (currentState is PaywallState.Loaded.Components) {
+                currentState.update(webViewMessageHandler = options.webViewMessageHandler)
+                workflowStepStateCache.values.forEach {
+                    it.update(webViewMessageHandler = options.webViewMessageHandler)
+                }
+            }
         }
     }
 
@@ -1186,7 +1199,12 @@ internal class PaywallViewModelImpl(
                 }
                 if (computed is PaywallState.Loaded.Components && stepId !in workflowStepStateCache) {
                     workflowStepStateCache[stepId] = computed
+                    // Re-stamp the locale and web view message handler from the latest values at insertion
+                    // time: this step's state was computed on the background dispatcher with a snapshot
+                    // taken before any concurrent updateOptions/locale change, and updateOptions only
+                    // refreshes steps already present in the cache when it runs.
                     computed.update(localeList = _lastLocaleList.value.toFrameworkLocaleList())
+                    computed.update(webViewMessageHandler = options.webViewMessageHandler)
                     workflow.singleStepFallbackId
                         ?.let { workflowStepStateCache[it]?.selectedPackageInfo }
                         ?.let { computed.setDefaultPackage(it) }
@@ -1459,6 +1477,7 @@ internal class PaywallViewModelImpl(
                 purchases = purchases,
                 customVariables = options.customVariables,
                 defaultCustomVariables = extractDefaultCustomVariables(offering),
+                webViewMessageHandler = options.webViewMessageHandler,
             )
         }
     }
diff --git a/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/helpers/OfferingToStateMapper.kt b/ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/helpers/OfferingToStateMapper.kt
@@ -36,6 +36,7 @@ import com.revenuecat.purchases.paywalls.components.properties.Size
 import com.revenuecat.purchases.paywalls.components.properties.SizeConstraint
 import com.revenuecat.purchases.ui.revenuecatui.CustomVariableValue
 import com.revenuecat.purchases.ui.revenuecatui.PaywallMode
+import com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler
 import com.revenuecat.purchases.ui.revenuecatui.components.ktx.getBestMatch
 import com.revenuecat.purchases.ui.revenuecatui.components.properties.FontSpec
 import com.revenuecat.purchases.ui.revenuecatui.components.properties.determineFontSpecs
@@ -367,6 +368,7 @@ internal fun Offering.toComponentsPaywallState(
     purchases: PurchasesType,
     customVariables: Map<String, CustomVariableValue> = emptyMap(),
     defaultCustomVariables: Map<String, CustomVariableValue> = emptyMap(),
+    webViewMessageHandler: PaywallWebViewMessageHandler? = null,
 ): PaywallState.Loaded.Components {
     val showPricesWithDecimals = storefrontCountryCode?.let {
         !validationResult.zeroDecimalPlaceCountries.contains(it)
@@ -387,6 +389,7 @@ internal fun Offering.toComponentsPaywallState(
         packages = validationResult.packages,
         customVariables = customVariables,
         defaultCustomVariables = defaultCustomVariables,
+        initialWebViewMessageHandler = webViewMessageHandler,
         initialSelectedTabIndex = validationResult.initialSelectedTabIndex,
         mainStackHasHeroImage = validationResult.mainStackHasHeroImage,
         purchases = purchases,
diff --git a/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallOptionsWebViewHandlerTest.kt b/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallOptionsWebViewHandlerTest.kt
@@ -0,0 +1,44 @@
+package com.revenuecat.purchases.ui.revenuecatui
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+internal class PaywallOptionsWebViewHandlerTest {
+
+    private fun options(handler: PaywallWebViewMessageHandler?): PaywallOptions =
+        PaywallOptions.Builder(dismissRequest = {})
+            .setWebViewMessageHandler(handler)
+            .build()
+
+    @Test
+    fun `builder stores the web view message handler`() {
+        val handler = PaywallWebViewMessageHandler { _, _ -> }
+
+        assertThat(options(handler).webViewMessageHandler).isSameAs(handler)
+    }
+
+    @Test
+    fun `defaults to no web view message handler`() {
+        val options = PaywallOptions.Builder(dismissRequest = {}).build()
+
+        assertThat(options.webViewMessageHandler).isNull()
+    }
+
+    @Test
+    fun `options differing only by handler are not equal`() {
+        val handlerA = PaywallWebViewMessageHandler { _, _ -> }
+        val handlerB = PaywallWebViewMessageHandler { _, _ -> }
+
+        assertThat(options(handlerA)).isNotEqualTo(options(handlerB))
+    }
+
+    @Test
+    fun `handler is excluded from hashCode so state updates are not triggered by it alone`() {
+        val handlerA = PaywallWebViewMessageHandler { _, _ -> }
+        val handlerB = PaywallWebViewMessageHandler { _, _ -> }
+
+        // hashCode intentionally ignores the handler (like listener) so swapping handlers does not
+        // force a paywall state refresh; see PaywallViewModel.updateOptions.
+        assertThat(options(handlerA).hashCode()).isEqualTo(options(handlerB).hashCode())
+    }
+}
diff --git a/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/style/StyleFactoryTests.kt b/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/components/style/StyleFactoryTests.kt
@@ -136,6 +136,7 @@ class StyleFactoryTests {
         assertThat(style.url).isEqualTo("https://paywalls.revenuecat.com/{{ custom.animal }}.html")
         assertThat(style.visible).isFalse()
         assertThat(style.size).isEqualTo(size)
+        assertThat(style.componentId).isEqualTo("promo_web_view")
         assertThat(style.protocolVersion).isNull()
     }
 
diff --git a/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModelTest.kt b/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModelTest.kt
@@ -49,6 +49,7 @@ import com.revenuecat.purchases.ui.revenuecatui.OfferingSelection
 import com.revenuecat.purchases.ui.revenuecatui.PaywallListener
 import com.revenuecat.purchases.ui.revenuecatui.PaywallMode
 import com.revenuecat.purchases.ui.revenuecatui.PaywallOptions
+import com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler
 import com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogicParams
 import com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic
 import com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogicWithCallback
@@ -661,6 +662,44 @@ class PaywallViewModelTest {
         coVerify(exactly = 1) { purchases.awaitOfferings() }
     }
 
+    @Test
+    fun `updateOptions refreshes the web view message handler in place without rebuilding`(): Unit = runBlocking {
+        val offering = Offering(
+            identifier = "offering-id",
+            serverDescription = "description",
+            metadata = emptyMap(),
+            availablePackages = listOf(TestData.Packages.monthly, TestData.Packages.annual),
+            paywallComponents = Offering.PaywallComponents(UiConfig(), emptyPaywallComponentsData),
+        )
+        val handlerA = PaywallWebViewMessageHandler { _, _ -> }
+        val handlerB = PaywallWebViewMessageHandler { _, _ -> }
+        fun optionsWith(handler: PaywallWebViewMessageHandler) =
+            PaywallOptions.Builder(dismissRequest = { dismissInvoked = true })
+                .setListener(listener)
+                .setOffering(offering)
+                .setWebViewMessageHandler(handler)
+                .build()
+
+        val model = PaywallViewModelImpl(
+            MockResourceProvider(),
+            purchases,
+            optionsWith(handlerA),
+            TestData.Constants.currentColorScheme,
+            isDarkMode = false,
+            shouldDisplayBlock = null,
+        )
+        val state = model.state.value as PaywallState.Loaded.Components
+        assertThat(state.webViewMessageHandler).isSameAs(handlerA)
+
+        // Same paywall, only the handler differs (handler is excluded from hashCode).
+        model.updateOptions(optionsWith(handlerB))
+
+        // No rebuild: the loaded state instance is preserved (same selections/scroll), and it now
+        // carries the new handler so web_view components see the latest one.
+        assertThat(model.state.value).isSameAs(state)
+        assertThat(state.webViewMessageHandler).isSameAs(handlerB)
+    }
+
     @Test
     fun `Should load default offering`() {
         val model = create()
diff --git a/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModelWorkflowTest.kt b/ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/data/PaywallViewModelWorkflowTest.kt

Original file line number	Diff line number	Diff line change
`@@ -136,6 +136,7 @@ class StyleFactoryTests {`
`136`	`136`	`assertThat(style.url).isEqualTo("https://paywalls.revenuecat.com/{{ custom.animal }}.html")`
`137`	`137`	`assertThat(style.visible).isFalse()`
`138`	`138`	`assertThat(style.size).isEqualTo(size)`
	`139`	`+ assertThat(style.componentId).isEqualTo("promo_web_view")`
`139`	`140`	`assertThat(style.protocolVersion).isNull()`
`140`	`141`	`}`
`141`	`142`