Add PaywallWarning model and validation documentation by JZDesign · Pull Request #6341 · RevenueCat/purchases-ios

JZDesign · 2026-02-23T20:28:00Z

Summary

Adds PaywallWarning enum mapping PaywallValidationError cases to user-facing titles, body text, and help URLs (RevenueCat dashboard/docs links)
Adds comprehensive documentation to PaywallData+Validation.swift explaining each error case, when it occurs, and how to resolve it

Stacked PRs breaking up #5930

This is PR 3 of 5 for the fallback paywall feature:

Color computation helpers Add color computation helpers for fallback paywall #6339
App style extractor + tests Add app style extractor for icon color extraction #6340
PaywallWarning model + docs Add PaywallWarning model and validation documentation #6341 (this PR)
DefaultPaywall UI + assets ← base: PR 3 Add default/fallback paywall UI components and assets #6342
Wire into PaywallView - Feature: Update fallback paywall #6359
Remove giant image and update snapshots

Test plan

Build succeeds on all platforms
No functional changes — data model and documentation only

🤖 Generated with Claude Code

Note

Low Risk
Low risk: adds a new warning model and documentation only, with no changes to paywall validation logic or runtime behavior.

Overview
Adds a new PaywallWarning enum that converts Offering.PaywallValidationError (and a few non-validation states like missing offering/products) into user-facing title, bodyText, and optional helpURL for linking to relevant RevenueCat docs.

Expands inline documentation for PaywallValidationError in PaywallData+Validation.swift, describing when each validation error occurs and how fallback paywall behavior is handled.

^{Written by Cursor Bugbot for commit d3cc5f4. This will update automatically on new commits. Configure here.}

Adds ColorComputationHelpers.swift with pure utility functions for: - WCAG 2.1 relative luminance and contrast ratio calculations - sRGB linearization (gamma correction removal) - Platform-agnostic RGB component extraction - Best-contrast color selection from a candidate set These will be used by the upcoming fallback paywall to adaptively choose text colors with sufficient contrast against backgrounds. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Adds AppStyleExtractor which extracts the app icon, display name, and prominent colors from the host app bundle. Uses pixel sampling with color quantization to identify 1-2 dominant colors from the app icon, filtering transparent/extreme brightness pixels. Also adds: - DualColorImageGenerator (DEBUG only) for creating deterministic test images with known color splits - AppStyleExtractorTests covering accuracy for multiple color combinations and edge cases (nil, transparent, dark/bright) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…nto jzdesign/fallback-paywall-2-app-style-extractor

Remove unreachable non-static instance methods from ColorComputationHelpers enum (dead code left over from global-to-enum conversion). Update tests to use qualified ColorComputationHelpers.method() calls. Co-authored-by: Cursor <cursoragent@cursor.com>

…nto jzdesign/fallback-paywall-2-app-style-extractor

facumenzella · 2026-02-25T12:05:39Z

The Set ordering in bodyText for .invalidVariables and .invalidIcons is non-deterministic — Set<String>.joined() can produce different output on each run.

Consider sorting before joining:

case .invalidVariables(let set):
    return "The following variables are not recognized: \(set.sorted().joined(separator: ", "))..."
case .invalidIcons(let set):
    return "The following icon names are not valid: \(set.sorted().joined(separator: ", "))..."

This ensures consistent UX and avoids potential flaky snapshot tests if the warning UI is ever snapshotted.

@mainactor

- Add @mainactor to AppIconDetailProvider since it is an ObservableObject with @published properties - Add #if !os(watchOS) guards in AppStyleExtractor for icon loading — watchOS app icons are system-managed with no runtime API to load them - Fix toAppIconDetailprovider -> toAppIconDetailProvider typo Co-authored-by: Cursor <cursoragent@cursor.com>

Adds PaywallWarning enum that maps PaywallValidationError cases to user-facing titles, body text, and help URLs linking to the RevenueCat dashboard or docs. This model will power the debug warning banner in the upcoming fallback paywall. Also adds comprehensive documentation to PaywallData+Validation.swift explaining each validation error case, when it occurs, and how to resolve it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Fix "Unkown" -> "Unknown" in invalidTemplate title. Add .missingLocalization to the helpURL case group so it returns the paywalls docs URL instead of nil. Co-authored-by: Cursor <cursoragent@cursor.com>

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

cursor · 2026-02-25T15:32:56Z

+        case .invalidVariables:
+            return URL(string: "https://www.revenuecat.com/docs/tools/paywalls/creating-paywalls/variables")
+        default:
+            return nil


Missing help links for some warnings

Low Severity

helpURL falls through to nil for invalidTemplate and invalidIcons, so those validation warnings have no documentation link while other paywall validation warnings do. This creates inconsistent warning behavior and removes in-context guidance for two known error cases.

This are not things that the user can work on, so no link was Hidde's thought IIRC

@mainactor

* Add color computation helpers for WCAG-compliant contrast calculations Adds ColorComputationHelpers.swift with pure utility functions for: - WCAG 2.1 relative luminance and contrast ratio calculations - sRGB linearization (gamma correction removal) - Platform-agnostic RGB component extraction - Best-contrast color selection from a candidate set These will be used by the upcoming fallback paywall to adaptively choose text colors with sufficient contrast against backgrounds. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add app style extractor for icon color extraction Adds AppStyleExtractor which extracts the app icon, display name, and prominent colors from the host app bundle. Uses pixel sampling with color quantization to identify 1-2 dominant colors from the app icon, filtering transparent/extreme brightness pixels. Also adds: - DualColorImageGenerator (DEBUG only) for creating deterministic test images with known color splits - AppStyleExtractorTests covering accuracy for multiple color combinations and edge cases (nil, transparent, dark/bright) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * PR Feedback * Create AppIconDetailProvider.swift * Update project.pbxproj * Remove duplicate instance methods and qualify test calls Remove unreachable non-static instance methods from ColorComputationHelpers enum (dead code left over from global-to-enum conversion). Update tests to use qualified ColorComputationHelpers.method() calls. Co-authored-by: Cursor <cursoragent@cursor.com> * Add @mainactor, fix watchOS icon guards, fix typo - Add @mainactor to AppIconDetailProvider since it is an ObservableObject with @published properties - Add #if !os(watchOS) guards in AppStyleExtractor for icon loading — watchOS app icons are system-managed with no runtime API to load them - Fix toAppIconDetailprovider -> toAppIconDetailProvider typo Co-authored-by: Cursor <cursoragent@cursor.com> * correct use of main actor * address cursor comment about brightness filter * import Combine needed for watchos to compile and build -> @published * Add PaywallWarning model and validation documentation Adds PaywallWarning enum that maps PaywallValidationError cases to user-facing titles, body text, and help URLs linking to the RevenueCat dashboard or docs. This model will power the debug warning banner in the upcoming fallback paywall. Also adds comprehensive documentation to PaywallData+Validation.swift explaining each validation error case, when it occurs, and how to resolve it. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Fix typo and add missing helpURL for missingLocalization Fix "Unkown" -> "Unknown" in invalidTemplate title. Add .missingLocalization to the helpURL case group so it returns the paywalls docs URL instead of nil. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>

JZDesign and others added 2 commits February 23, 2026 14:15

JZDesign requested a review from a team as a code owner February 23, 2026 20:28

cursor Bot reviewed Feb 23, 2026

View reviewed changes

Comment thread RevenueCatUI/Helpers/PaywallWarning.swift Outdated

Comment thread RevenueCatUI/Helpers/PaywallWarning.swift

JZDesign added the pr:other label Feb 23, 2026

This was referenced Feb 23, 2026

Add default/fallback paywall UI components and assets #6342

Merged

Add app style extractor for icon color extraction #6340

Merged

Add color computation helpers for fallback paywall #6339

Merged

JZDesign and others added 5 commits February 24, 2026 07:56

PR Feedback

be3b292

Create AppIconDetailProvider.swift

7b0d025

Merge branch 'main' of https://github.com//RevenueCat/purchases-ios i…

25ed71c

…nto jzdesign/fallback-paywall-2-app-style-extractor

Update project.pbxproj

c229b47

JZDesign force-pushed the jzdesign/fallback-paywall-3-paywall-warning branch from 8e25223 to 606081b Compare February 24, 2026 21:01

JZDesign requested a review from a team as a code owner February 24, 2026 21:01

cursor Bot reviewed Feb 24, 2026

View reviewed changes

Comment thread RevenueCatUI/Helpers/PaywallWarning.swift

Comment thread RevenueCatUI/Helpers/PaywallWarning.swift

Merge branch 'main' of https://github.com//RevenueCat/purchases-ios i…

c95d323

…nto jzdesign/fallback-paywall-2-app-style-extractor

JZDesign force-pushed the jzdesign/fallback-paywall-3-paywall-warning branch from 606081b to 5e9167b Compare February 25, 2026 13:43

correct use of main actor

9fc7c3b

JZDesign force-pushed the jzdesign/fallback-paywall-3-paywall-warning branch from 5e9167b to 4202bca Compare February 25, 2026 14:45

JZDesign and others added 4 commits February 25, 2026 09:01

address cursor comment about brightness filter

05e8b59

import Combine needed for watchos to compile and build -> @published

b51bb3e

Fix typo and add missing helpURL for missingLocalization

1f253ce

Fix "Unkown" -> "Unknown" in invalidTemplate title. Add .missingLocalization to the helpURL case group so it returns the paywalls docs URL instead of nil. Co-authored-by: Cursor <cursoragent@cursor.com>

JZDesign force-pushed the jzdesign/fallback-paywall-3-paywall-warning branch from 4202bca to 1f253ce Compare February 25, 2026 15:18

cursor Bot reviewed Feb 25, 2026

View reviewed changes

Base automatically changed from jzdesign/fallback-paywall-2-app-style-extractor to main February 25, 2026 20:01

JZDesign mentioned this pull request Feb 25, 2026

Feature: Update fallback paywall #6359

Merged

2 tasks

Merge branch 'main' into jzdesign/fallback-paywall-3-paywall-warning

d3cc5f4

facumenzella approved these changes Feb 26, 2026

View reviewed changes

JZDesign merged commit e0ff600 into main Feb 27, 2026
14 of 15 checks passed

JZDesign deleted the jzdesign/fallback-paywall-3-paywall-warning branch February 27, 2026 12:53

This was referenced Mar 4, 2026

[AUTOMATIC] Release/5.60.1 #6401

Closed

[AUTOMATIC] Release/5.60.1 #6403

Closed

This was referenced Mar 6, 2026

[AUTOMATIC] Release/5.61.0 #6410

Closed

[AUTOMATIC] Release/5.61.0 #6414

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add PaywallWarning model and validation documentation#6341

Add PaywallWarning model and validation documentation#6341
JZDesign merged 15 commits intomainfrom
jzdesign/fallback-paywall-3-paywall-warning

JZDesign commented Feb 23, 2026 •

edited by cursor Bot

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

facumenzella commented Feb 25, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Feb 25, 2026

Uh oh!

JZDesign Feb 25, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

JZDesign commented Feb 23, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Stacked PRs breaking up #5930

Test plan

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

facumenzella commented Feb 25, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Feb 25, 2026

Choose a reason for hiding this comment

Missing help links for some warnings

Uh oh!

JZDesign Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JZDesign commented Feb 23, 2026 •

edited by cursor Bot

Loading