RevenueCat · JZDesign · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026 · Jul 15, 2026
@@ -101,6 +101,8 @@ struct ComponentsView: View {
             VideoComponentView(viewModel: viewModel)
         case .countdown(let viewModel):
             CountdownComponentView(viewModel: viewModel, onDismiss: onDismiss)
+        case .webView(let viewModel):
+            WebViewComponentView(viewModel: viewModel)
         }
     }
 }

@@ -14,7 +14,7 @@ final class WebViewComponentViewModel: Hashable {
     let visible: Bool
     let componentID: String
 
-    lazy var url: URL? = Self.validatedHTTPSURL(from: self.urlString)
+    lazy var url: URL? = PaywallComponent.WebViewComponent.validatedHTTPSURL(from: self.urlString)
 
     #if canImport(WebKit)
     /// Canonical origin derived from ``url``. Because ``url`` is already validated as HTTPS with a
@@ -44,16 +44,6 @@ final class WebViewComponentViewModel: Hashable {
         self.componentID = component.id
     }
 
-    private static func validatedHTTPSURL(from urlString: String) -> URL? {
-        guard !urlString.contains("{{"),
-              let url = URL(string: urlString),
-              url.scheme?.lowercased() == "https",
-              url.host?.isEmpty == false else {
-            return nil
-        }
-        return url
-    }
-
     func hash(into hasher: inout Hasher) {
         hasher.combine(self.urlString)
         hasher.combine(self.componentID)

@@ -3,6 +3,7 @@
 //
 
 import Foundation
+@_spi(Internal) import RevenueCat
 
 #if !os(tvOS) // For Paywalls V2
 
@@ -13,7 +14,7 @@ enum WebViewEnvelope {
     static let messageHandlerName = "rcWebComponents"
     /// Name of the JS function injected into the web view that receives host-to-content frames.
     static let receiveFunction = "__rcWebComponentsReceive"
-    static let defaultProtocolVersion = 1
+    static let defaultProtocolVersion = PaywallComponent.WebViewComponent.supportedProtocolVersion
 
     static let messageTypeResize = "resize"
     static let messageTypeFit = "fit"

@@ -39,6 +39,7 @@ enum PaywallComponentViewModel {
     case carousel(CarouselComponentViewModel)
     case video(VideoComponentViewModel)
     case countdown(CountdownComponentViewModel)
+    case webView(WebViewComponentViewModel)
 }
 
 #endif
@@ -461,6 +461,8 @@ extension PaywallComponent {
             return component.containsUnsupportedConditions()
         case .countdown(let component):
             return component.containsUnsupportedConditions()
+        case .webView:
+            return false
         case .fallbackHeader:
             return false
         }

@@ -513,6 +513,10 @@ struct ViewModelFactory {
                     fallbackStackViewModel: fallbackStackViewModel
                 )
             )
+        case .webView(let component):
+            return .webView(
+                WebViewComponentViewModel(component: component)
+            )
         case .fallbackHeader:
             // fallbackHeader is filtered out in toStackViewModel and should never reach here.
             assertionFailure("fallbackHeader should have been filtered before view model creation")

@@ -32,6 +32,8 @@ import Foundation
 
     case countdown(CountdownComponent)
 
+    case webView(WebViewComponent)
+
     case fallbackHeader
 
     public enum ComponentType: String, Codable, Sendable {
@@ -54,6 +56,7 @@ import Foundation
         case carousel
         case video
         case countdown
+        case webView = "web_view"
         case fallbackHeader = "fallback_header"
 
     }
@@ -73,6 +76,7 @@ import Foundation
 
         case type
         case fallback
+        case protocolVersion
 
     }
 
@@ -129,6 +133,9 @@ import Foundation
         case .countdown(let component):
             try container.encode(ComponentType.countdown, forKey: .type)
             try component.encode(to: encoder)
+        case .webView(let component):
+            try container.encode(ComponentType.webView, forKey: .type)
+            try component.encode(to: encoder)
         case .fallbackHeader:
             try container.encode(ComponentType.fallbackHeader, forKey: .type)
         }
@@ -144,41 +151,74 @@ import Foundation
         if let type = ComponentType(rawValue: typeString) {
             self = try Self.decodeType(from: decoder, type: type)
         } else {
-            if !container.contains(.fallback) {
-                let context = DecodingError.Context(
-                    codingPath: container.codingPath,
-                    debugDescription:
-                      """
-                      Failed to decode unknown type "\(typeString)" without a fallback.
-                      """
-                )
-                throw DecodingError.dataCorrupted(context)
+            // If `typeString` is unknown, render the author-provided fallback.
+            self = try Self.decodeFallback(from: decoder, reason: .unknownType(typeString))
+        }
+    }
+
+    /// Explains why a component is being decoded through its author-provided `fallback`, so the
+    /// resulting `DecodingError` points at the real cause when no usable fallback is present.
+    private enum FallbackReason {
+
+        /// The component `type` string is not recognized by this SDK.
+        case unknownType(String)
+
+        /// A `web_view` component this SDK cannot service (e.g. unsupported platform or
+        /// `protocol_version`). The associated value describes the specific cause.
+        case unserviceableWebView(String)
+
+        /// Error description used when no `fallback` is present.
+        var missingFallbackDescription: String {
+            switch self {
+            case let .unknownType(typeString):
+                return "Failed to decode unknown type \"\(typeString)\" without a fallback."
+            case let .unserviceableWebView(detail):
+                return "Failed to decode web_view component without a fallback: \(detail)."
             }
+        }
 
-            do {
-                // If `typeString` is unknown, try to decode the fallback
-                self = try container.decode(PaywallComponent.self, forKey: .fallback)
-            } catch DecodingError.valueNotFound {
-                let context = DecodingError.Context(
-                    codingPath: container.codingPath,
-                    debugDescription:
-                      """
-                      Failed to decode unknown type "\(typeString)" without a fallback.
-                      """
-                )
-                throw DecodingError.dataCorrupted(context)
-            } catch {
-                let context = DecodingError.Context(
-                    codingPath: container.codingPath,
-                    debugDescription:
-                      """
-                      Failed to decode fallback for unknown type "\(typeString)".
-                      """,
-                    underlyingError: error
-                )
-                throw DecodingError.dataCorrupted(context)
+        /// Error description used when a `fallback` is present but cannot be decoded.
+        var failedFallbackDescription: String {
+            switch self {
+            case let .unknownType(typeString):
+                return "Failed to decode fallback for unknown type \"\(typeString)\"."
+            case let .unserviceableWebView(detail):
+                return "Failed to decode fallback for web_view component: \(detail)."
             }
         }
+
+    }
+
+    /// Decodes the author-provided `fallback` component, used both for unknown component types and
+    /// for known components this SDK version cannot service (e.g. an unsupported `web_view`
+    /// `protocol_version`). Throws a `reason`-specific error if no usable fallback is present.
+    private static func decodeFallback(from decoder: Decoder, reason: FallbackReason) throws -> PaywallComponent {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        guard container.contains(.fallback) else {
+            let context = DecodingError.Context(
+                codingPath: container.codingPath,
+                debugDescription: reason.missingFallbackDescription
+            )
+            throw DecodingError.dataCorrupted(context)
+        }
+
+        do {
+            return try container.decode(PaywallComponent.self, forKey: .fallback)
+        } catch DecodingError.valueNotFound {
+            let context = DecodingError.Context(
+                codingPath: container.codingPath,
+                debugDescription: reason.missingFallbackDescription
+            )
+            throw DecodingError.dataCorrupted(context)
+        } catch {
+            let context = DecodingError.Context(
+                codingPath: container.codingPath,
+                debugDescription: reason.failedFallbackDescription,
+                underlyingError: error
+            )
+            throw DecodingError.dataCorrupted(context)
+        }
     }
 
     // swiftlint:disable:next cyclomatic_complexity
@@ -216,9 +256,46 @@ import Foundation
             return .video(try VideoComponent(from: decoder))
         case .countdown:
             return .countdown(try CountdownComponent(from: decoder))
+        case .webView:
+            return try Self.decodeWebView(from: decoder)
         case .fallbackHeader:
             return .fallbackHeader
         }
     }
 
+    private static func decodeWebView(from decoder: Decoder) throws -> PaywallComponent {
+        #if os(watchOS) || os(tvOS) || !canImport(WebKit)
+        return try Self.decodeFallback(
+            from: decoder,
+            reason: .unserviceableWebView("web views are not supported on this platform")
+        )
+        #else
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        // Gate a valid raw version before decoding the full model. This lets a newer protocol use
+        // its fallback without requiring this SDK to understand that protocol's remaining fields.
+        let protocolVersion = try container.decode(Int.self, forKey: .protocolVersion)
+        guard protocolVersion == WebViewComponent.supportedProtocolVersion else {
+            return try Self.decodeFallback(
+                from: decoder,
+                reason: .unserviceableWebView(
+                    "unsupported protocol_version \(protocolVersion) " +
+                    "(this SDK supports \(WebViewComponent.supportedProtocolVersion))"
+                )
+            )
+        }
+
+        let component = try WebViewComponent(from: decoder)
+        if let validationError = component.configurationValidationError {
+            let context = DecodingError.Context(
+                codingPath: decoder.codingPath,
+                debugDescription: validationError
+            )
+            throw DecodingError.dataCorrupted(context)
+        }
+
+        return .webView(component)
+        #endif
+    }
+
 }
@@ -208,7 +208,7 @@ extension PaywallComponentsData.PaywallComponentsConfig {
                         includeHighResInComponentHeirarchy: includeHighResInComponentHeirarchy
                     )
                 }
-            case .fallbackHeader:
+            case .webView, .fallbackHeader:
                 break
             }
         }
@@ -265,7 +265,7 @@ extension PaywallComponentsData.PaywallComponentsConfig {
                 if let fallback = countdown.fallback {
                     urls += self.collectAllVideoURLs(in: fallback)
                 }
-            case .fallbackHeader:
+            case .webView, .fallbackHeader:
                 break
             }
         }

@@ -17,8 +17,11 @@ import Foundation
 
     final class WebViewComponent: PaywallComponentBase {
 
-        /// Wire `type` value, kept as a `String` because `web_view` is not yet a `ComponentType` case.
-        let type: String
+        /// The host<->component bridge protocol version this SDK implements. A config declaring any
+        /// other version is treated as an unrecognized component and rendered via its `fallback`.
+        public static let supportedProtocolVersion: Int = 1
+
+        let type: ComponentType
         public let id: String
         public let name: String?
         public let visible: Bool?
@@ -30,6 +33,31 @@ import Foundation
 
         public let size: Size
 
+        /// Resolves a URL that is safe to use as a web view component entry point.
+        public static func validatedHTTPSURL(from urlString: String) -> URL? {
+            guard !urlString.contains("{{"),
+                  let url = URL(string: urlString),
+                  url.scheme?.lowercased() == "https",
+                  url.host?.isEmpty == false else {
+                return nil
+            }
+
+            return url
+        }
+
+        /// Describes why the decoded static configuration is invalid, if applicable.
+        var configurationValidationError: String? {
+            if self.id.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                return "Web view component ID must not be blank."
+            }
+
+            guard Self.validatedHTTPSURL(from: self.url) != nil else {
+                return "Web view component URL must be a resolved HTTPS URL with a host."
+            }
+
+            return nil
+        }
+
         public init(
             id: String,
             name: String? = nil,
@@ -38,7 +66,7 @@ import Foundation
             url: String,
             size: Size = .init(width: .fill, height: .fit(nil))
         ) {
-            self.type = "web_view"
+            self.type = .webView
             self.id = id
             self.name = name
             self.visible = visible