# SuperwallOptions

A configuration class for customizing paywall appearance and behavior.

> **Warning**

Only modify `networkEnvironment` if explicitly instructed by the Superwall team. Use `.release` (default) for production apps.



> **Tip**

Use different `SuperwallOptions` configurations for debug and release builds to optimize logging and behavior for each environment.



> **Note**

The SDK automatically chooses StoreKit 2 on iOS 15+ and falls back to StoreKit 1 on older versions, but you can override this with `storeKitVersion`.



Purpose [#purpose]

Configures various aspects of Superwall behavior including paywall presentation, networking, logging, and StoreKit version preferences.

Signature [#signature]

```swift
@objcMembers
public final class SuperwallOptions: NSObject {
  public var paywalls: PaywallOptions
  public var storeKitVersion: StoreKitVersion
  public var networkEnvironment: NetworkEnvironment
  public var logging: LoggingOptions
  public var localeIdentifier: String?
  public var shouldBypassAppTransactionCheck: Bool
  public var testModeBehavior: TestModeBehavior
  public var localResources: [String: AssetResource]
}
```

Parameters [#parameters]

<TypeTable
  type="{
  paywalls: {
    type: &#x22;PaywallOptions&#x22;,
    typeDescriptionLink: &#x22;/ios/sdk-reference/PaywallOptions&#x22;,
    description: &#x22;Configuration for paywall appearance and behavior.&#x22;,
    required: true,
  },
  storeKitVersion: {
    type: &#x22;StoreKitVersion&#x22;,
    description: &#x22;Preferred StoreKit version (`.storeKit1` or `.storeKit2`).&#x22;,
    default: &#x22;StoreKit 2 on iOS 15+&#x22;,
  },
  networkEnvironment: {
    type: &#x22;NetworkEnvironment&#x22;,
    description: &#x22;Network environment (`.release`, `.releaseCandidate`, `.developer`, `.custom(String)`). **Use only if instructed by Superwall team.**&#x22;,
    required: true,
  },
  logging: {
    type: &#x22;LoggingOptions&#x22;,
    description: &#x22;Logging configuration including level and scopes.&#x22;,
    required: true,
  },
  localeIdentifier: {
    type: &#x22;String?&#x22;,
    description: &#x22;Override locale for paywall localization (e.g., \&#x22;en_GB\&#x22;).&#x22;,
  },
  shouldBypassAppTransactionCheck: {
    type: &#x22;Bool&#x22;,
    description: &#x22;Disables the app transaction check on SDK launch. Useful in testing environments to avoid triggering the Apple ID sign-in prompt. Available in version 4.9.0+.&#x22;,
    default: &#x22;false&#x22;,
  },
  testModeBehavior: {
    type: &#x22;TestModeBehavior&#x22;,
    description:
      &#x22;Controls when the SDK enters test mode. Options: `.automatic`, `.whenEnabledForUser`, `.always`, `.never`. See the [Test Mode guide](/ios/guides/test-mode) for details.&#x22;,
    default: &#x22;.automatic&#x22;,
  },
  localResources: {
    type: &#x22;[String: AssetResource]&#x22;,
    description:
      &#x22;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.&#x22;,
    default: &#x22;[:]&#x22;,
  },
}"
/>

Returns / State [#returns--state]

This is a configuration object used when calling [`configure()`](/docs/ios/sdk-reference/configure).

Usage [#usage]

Basic options setup:

```swift
let options = SuperwallOptions()

// Configure paywall behavior
options.paywalls.shouldShowPurchaseFailureAlert = false
options.paywalls.shouldAutoShowPurchaseLoadingIndicator = true
options.paywalls.automaticallyDismiss = true

// Set StoreKit version preference
options.storeKitVersion = .storeKit2

// Configure logging
options.logging.level = .warn
options.logging.scopes = [.superwallCore, .paywallViewController]

// Set locale for testing
options.localeIdentifier = "en_GB"

// Bypass app transaction check (useful for testing)
options.shouldBypassAppTransactionCheck = true

// Use with configure
Superwall.configure(
  apiKey: "pk_your_api_key",
  options: options
)
```

PaywallOptions configuration:

```swift
let paywallOptions = PaywallOptions()

// Presentation behavior
paywallOptions.shouldShowPurchaseFailureAlert = false
paywallOptions.shouldAutoShowPurchaseLoadingIndicator = true
paywallOptions.automaticallyDismiss = true

// Transaction behavior  
paywallOptions.transactionTimeout = 30.0 // seconds
paywallOptions.restoreFailedPurchaseAlert.title = "Restore Failed"
paywallOptions.restoreFailedPurchaseAlert.message = "Please try again"

// Product overrides
paywallOptions.overrideProductsByName = [
  "primary": "produceID_to_replace_primary_product"
]
// Assign to main options
options.paywalls = paywallOptions
```

Logging configuration:

```swift
let loggingOptions = LoggingOptions()
loggingOptions.level = .debug
loggingOptions.scopes = [.all] // or specific scopes like [.superwallCore, .network]

options.logging = loggingOptions
```

Real-world example for production:

```swift
func configureSuperwallForProduction() {
  let options = SuperwallOptions()
  
  // Minimal logging for production
  options.logging.level = .error
  
  // Customize paywall behavior
  options.paywalls.shouldShowPurchaseFailureAlert = true
  options.paywalls.automaticallyDismiss = true
  
  // Use StoreKit 2 for better performance on iOS 15+
  options.storeKitVersion = .storeKit2
  
  Superwall.configure(
    apiKey: "pk_your_production_api_key",
    options: options
  )
}
```

Debug configuration for development:

```swift
func configureSuperwallForDebug() {
  let options = SuperwallOptions()
  
  // Verbose logging for debugging
  options.logging.level = .debug
  options.logging.scopes = [.all]
  
  // Show detailed error alerts
  options.paywalls.shouldShowPurchaseFailureAlert = true
  
  // Test with specific locale
  options.localeIdentifier = "es_ES"
  
  Superwall.configure(
    apiKey: "pk_your_test_api_key",
    options: options
  )
}
```

Related [#related]

* [`PaywallOptions`](/docs/ios/sdk-reference/PaywallOptions)
* [`localResources`](/docs/ios/sdk-reference/localResources)

Runtime Interface Style Configuration [#runtime-interface-style-configuration]

While `SuperwallOptions` provides initial configuration, you can dynamically change the interface style (light/dark mode) for paywalls at runtime using:

```swift
// Force dark mode for all paywalls
Superwall.shared.setInterfaceStyle(to: .dark)

// Force light mode for all paywalls  
Superwall.shared.setInterfaceStyle(to: .light)

// Revert to system default
Superwall.shared.setInterfaceStyle(to: nil)
```

Use this method if you have a themeing system that is different than
the system.

The change takes effect immediately and persists until changed again or the app restarts.