Add PaywallDialogOptions.setWebViewMessageHandler

Thread the handler through to PaywallOptions when PaywallDialog builds
internally. Handler participates in equals but is excluded from hashCode,
mirroring PaywallOptions. Includes parity tests and api-tester coverage.

Co-authored-by: jacob.rakidzich <jacob.rakidzich@revenuecat.com>

Author: 2 people

api-tester/src/defaults/kotlin/com/revenuecat/apitester/kotlin/revenuecatui/PaywallDialogOptionsAPI.kt

@@ -24,6 +24,7 @@ private class PaywallDialogOptionsAPI {
             .setListener(listener)
             .setShouldDisplayDismissButton(true)
             .setFontProvider(fontProvider)
+            .setWebViewMessageHandler(null)
             .build()
         val shouldDisplayBlock2 = options.shouldDisplayBlock
         val offering2: Offering? = options.offering

ui/revenuecatui/api.txt

@@ -44,6 +44,7 @@ package com.revenuecat.purchases.ui.revenuecatui {
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic? getPurchaseLogic();
     method public kotlin.jvm.functions.Function1<com.revenuecat.purchases.CustomerInfo,java.lang.Boolean>? getShouldDisplayBlock();
     method public boolean getShouldDisplayDismissButton();
+    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;
@@ -52,6 +53,7 @@ package com.revenuecat.purchases.ui.revenuecatui {
     property public final com.revenuecat.purchases.ui.revenuecatui.PaywallPurchaseLogic? purchaseLogic;
     property public final kotlin.jvm.functions.Function1<com.revenuecat.purchases.CustomerInfo,java.lang.Boolean>? shouldDisplayBlock;
     property public final boolean shouldDisplayDismissButton;
+    property public final com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler? webViewMessageHandler;
   }
 
   public static final class PaywallDialogOptions.Builder {
@@ -66,6 +68,7 @@ package com.revenuecat.purchases.ui.revenuecatui {
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallDialogOptions.Builder setRequiredEntitlementIdentifier(String? requiredEntitlementIdentifier);
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallDialogOptions.Builder setShouldDisplayBlock(kotlin.jvm.functions.Function1<? super com.revenuecat.purchases.CustomerInfo,java.lang.Boolean>? shouldDisplayBlock);
     method public com.revenuecat.purchases.ui.revenuecatui.PaywallDialogOptions.Builder setShouldDisplayDismissButton(boolean shouldDisplayDismissButton);
+    method public com.revenuecat.purchases.ui.revenuecatui.PaywallDialogOptions.Builder setWebViewMessageHandler(com.revenuecat.purchases.ui.revenuecatui.PaywallWebViewMessageHandler? handler);
   }
 
   public final class PaywallFooterKt {

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallDialog.kt

@@ -132,5 +132,6 @@ private fun buildPaywallOptions(
         .setPurchaseLogic(paywallDialogOptions.purchaseLogic)
         .setDismissRequestWithExitOffering(dismissRequestWithExitOffering)
         .setCustomVariables(paywallDialogOptions.customVariables)
+        .setWebViewMessageHandler(paywallDialogOptions.webViewMessageHandler)
         .build()
 }

ui/revenuecatui/src/main/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallDialogOptions.kt

@@ -22,6 +22,10 @@ public class PaywallDialogOptions 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. See [PaywallWebViewMessageHandler].
+     */
+    public val webViewMessageHandler: PaywallWebViewMessageHandler? = null,
 ) {
 
     internal val offeringSelection: OfferingSelection
@@ -36,8 +40,40 @@ public class PaywallDialogOptions internal constructor(
         listener = builder.listener,
         purchaseLogic = builder.purchaseLogic,
         customVariables = builder.customVariables,
+        webViewMessageHandler = builder.webViewMessageHandler,
     )
 
+    public companion object {
+        private const val hashMultiplier = 31
+    }
+
+    // webViewMessageHandler is included in equals but excluded from hashCode (like PaywallOptions).
+    override fun hashCode(): Int {
+        var result = shouldDisplayDismissButton.hashCode()
+        result = hashMultiplier * result + customVariables.hashCode()
+        result = hashMultiplier * result + (offering?.identifier?.hashCode() ?: 0)
+        return result
+    }
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (other !is PaywallDialogOptions) return false
+
+        return when {
+            this.shouldDisplayBlock != other.shouldDisplayBlock -> false
+            this.dismissRequest != other.dismissRequest -> false
+            this.offering != other.offering -> false
+            this.shouldDisplayDismissButton != other.shouldDisplayDismissButton -> false
+            this.fontProvider != other.fontProvider -> false
+            this.listener != other.listener -> false
+            this.purchaseLogic != other.purchaseLogic -> false
+            this.customVariables != other.customVariables -> false
+            this.webViewMessageHandler != other.webViewMessageHandler -> false
+            else -> true
+        }
+    }
+
+    @Suppress("TooManyFunctions")
     public class Builder {
         internal var shouldDisplayBlock: ((CustomerInfo) -> Boolean)? = null
         internal var dismissRequest: (() -> Unit)? = null
@@ -47,6 +83,7 @@ public class PaywallDialogOptions internal constructor(
         internal var listener: PaywallListener? = null
         internal var purchaseLogic: PaywallPurchaseLogic? = null
         internal var customVariables: Map<String, CustomVariableValue> = emptyMap()
+        internal var webViewMessageHandler: PaywallWebViewMessageHandler? = null
 
         /**
          * Allows to configure whether to display the paywall dialog depending on operations on the CustomerInfo
@@ -106,6 +143,15 @@ public class PaywallDialogOptions internal constructor(
             this.customVariables = 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.
+         */
+        public fun setWebViewMessageHandler(handler: PaywallWebViewMessageHandler?): Builder = apply {
+            this.webViewMessageHandler = handler
+        }
+
         public fun build(): PaywallDialogOptions {
             return PaywallDialogOptions(this)
         }

ui/revenuecatui/src/test/kotlin/com/revenuecat/purchases/ui/revenuecatui/PaywallDialogOptionsWebViewHandlerTest.kt

@@ -0,0 +1,42 @@
+package com.revenuecat.purchases.ui.revenuecatui
+
+import org.assertj.core.api.Assertions.assertThat
+import org.junit.Test
+
+internal class PaywallDialogOptionsWebViewHandlerTest {
+
+    private fun options(handler: PaywallWebViewMessageHandler?): PaywallDialogOptions =
+        PaywallDialogOptions.Builder()
+            .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 = PaywallDialogOptions.Builder().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 { _, _ -> }
+
+        assertThat(options(handlerA).hashCode()).isEqualTo(options(handlerB).hashCode())
+    }
+}