From 7d839c5ce30decaac5029a5431291a2a433a2a91 Mon Sep 17 00:00:00 2001
From: wurdigmich <harshay.khetan@gmail.com>
Date: Fri, 14 Aug 2026 23:16:21 +0530
Subject: [PATCH] docs(ios): document six public APIs that only appear in the
 changelog
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

configurationStatus, isPaywallPresented, latestPaywallInfo, getAssignments,
togglePaywallSpinner and maxConfigRetryCount are all public and carry doc
comments in the SDK, but none of them appear on an SDK reference page or in a
guide — only in the changelog.

Adds them to the Superwall and SuperwallOptions reference pages, following the
existing usage-snippet and TypeTable patterns on those pages.
---
 content/docs/ios/sdk-reference/Superwall.mdx  | 60 +++++++++++++++++++
 .../ios/sdk-reference/SuperwallOptions.mdx    | 10 ++++
 2 files changed, 70 insertions(+)

diff --git a/content/docs/ios/sdk-reference/Superwall.mdx b/content/docs/ios/sdk-reference/Superwall.mdx
index e585d7bc..c12ac262 100644
--- a/content/docs/ios/sdk-reference/Superwall.mdx
+++ b/content/docs/ios/sdk-reference/Superwall.mdx
@@ -14,6 +14,13 @@ Provides access to the configured Superwall instance after calling [`configure()
 ```swift
 public static var shared: Superwall { get }
 public var eventTrackingBehavior: EventTrackingBehavior { get set }
+
+@Published public var configurationStatus: ConfigurationStatus { get }
+public var isPaywallPresented: Bool { get }
+public var latestPaywallInfo: PaywallInfo? { get }
+
+public func getAssignments() -> [Assignment]
+public func togglePaywallSpinner(isHidden: Bool)
 ```
 
 ## Parameters
@@ -114,6 +121,39 @@ let deviceAttributes = await Superwall.shared.getDeviceAttributes()
 print("Device attributes: \(deviceAttributes)")
 ```
 
+Observe configuration status:
+```swift
+// .pending until configuration finishes, then .configured or .failed
+switch Superwall.shared.configurationStatus {
+case .pending:
+  showLoadingState()
+case .configured:
+  showPaywallEntryPoints()
+case .failed:
+  showFallbackUI()
+}
+
+// It's a @Published property, so you can bind to it in SwiftUI or Combine
+Superwall.shared.$configurationStatus
+  .sink { status in
+    print("Superwall configuration is now \(status)")
+  }
+  .store(in: &cancellables)
+```
+
+Check whether a paywall is on screen:
+```swift
+if Superwall.shared.isPaywallPresented {
+  // Don't push another screen on top of the paywall
+  return
+}
+
+// Inspect the most recently presented paywall
+if let info = Superwall.shared.latestPaywallInfo {
+  print("Last paywall: \(info.identifier), experiment: \(info.experiment?.id ?? "none")")
+}
+```
+
 Confirm all experiment assignments:
 ```swift
 // Get all experiment assignments
@@ -121,6 +161,26 @@ let assignments = await Superwall.shared.confirmAllAssignments()
 print("Confirmed \(assignments.count) assignments")
 ```
 
+Read already-confirmed assignments:
+```swift
+// Synchronous, and does not confirm anything new — returns the assignments
+// already stored on device. Use confirmAllAssignments() to confirm them first.
+let assignments = Superwall.shared.getAssignments()
+```
+
+Show a spinner while doing async work from a custom paywall action:
+```swift
+func handleCustomPaywallAction(withName name: String) {
+  guard name == "restore_from_backend" else { return }
+
+  Superwall.shared.togglePaywallSpinner(isHidden: false)
+  Task {
+    await syncEntitlementsFromServer()
+    Superwall.shared.togglePaywallSpinner(isHidden: true)
+  }
+}
+```
+
 Manually refresh configuration (development-only):
 ```swift
 // Useful when hot-reloading paywalls during development
diff --git a/content/docs/ios/sdk-reference/SuperwallOptions.mdx b/content/docs/ios/sdk-reference/SuperwallOptions.mdx
index f2ff5fa1..cccd8b6c 100644
--- a/content/docs/ios/sdk-reference/SuperwallOptions.mdx
+++ b/content/docs/ios/sdk-reference/SuperwallOptions.mdx
@@ -33,6 +33,7 @@ public final class SuperwallOptions: NSObject {
   public var isExternalDataCollectionEnabled: Bool
   public var testModeBehavior: TestModeBehavior
   public var localResources: [String: AssetResource]
+  public var maxConfigRetryCount: Int
 }
 ```
 
@@ -93,6 +94,12 @@ public final class SuperwallOptions: NSObject {
         "A dictionary mapping resource IDs to local file URLs or asset catalog images. See [`localResources`](/ios/sdk-reference/localResources) for the property schema and the [Local Resources guide](/ios/guides/local-resources) for setup details.",
       default: "[:]",
     },
+    maxConfigRetryCount: {
+      type: "Int",
+      description:
+        "How many times the SDK retries fetching configuration after a network failure before giving up. Lower it to have [`register(placement:)`](/ios/sdk-reference/register) call the [`PaywallPresentationHandler`](/ios/sdk-reference/PaywallPresentationHandler) `onError` handler sooner on a bad connection. Values below `0` are clamped to `0`.",
+      default: "6",
+    },
   }}
 />
 
@@ -127,6 +134,9 @@ options.shouldBypassAppTransactionCheck = true
 // Control SDK event collection
 options.eventTrackingBehavior = .superwallOnly
 
+// Fail faster on a poor connection instead of retrying 6 times
+options.maxConfigRetryCount = 2
+
 // Use with configure
 Superwall.configure(
   apiKey: "pk_your_api_key",