Superwall iOS SDK

https://superwall.com/docs/ios
Admin
The Superwall iOS SDK helps developers integrate, manage, and track in-app subscriptions and...
Tokens:63,603
Snippets:867
Trust Score:9.5
Update:2 months ago
Show doc for...
Tokens:
Raw
### Usage Examples

Source: https://superwall.com/docs/ios/sdk-reference/getPresentationResult

Examples demonstrating how to handle the PresentationResult using both async/await and completion handler patterns.

```swift
let result = await Superwall.shared.getPresentationResult(
  forPlacement: "premium_feature",
  params: ["source": "settings"]
)

switch result {
case .paywall(let experiment):
  analytics.log("Paywall would show", metadata: [
    "experimentId": experiment.id,
    "groupId": experiment.groupId
  ])
case .holdout(let experiment):
  showHoldoutBadge(for: experiment)
case .noAudienceMatch:
  unlockFeature()
case .placementNotFound:
  assertionFailure("Missing campaign setup")
case .paywallNotAvailable:
  fallbackToDefaultFlow()
}
```

```swift
Superwall.shared.getPresentationResult(forPlacement: "premium_feature") { result in
  guard case .paywall(let experiment) = result else {
    return
  }

  // Update UI with experiment metadata while keeping the user on the current screen
  self.paywallExperimentId = experiment.id
}
```

--------------------------------

### Production Configuration Example

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Example of a minimal, production-ready configuration for the Superwall SDK.

```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
  )
}
```

--------------------------------

### getPaywall() Usage Examples

Source: https://superwall.com/docs/ios/sdk-reference/advanced/getPaywall

Examples demonstrating how to retrieve and present a paywall using both async/await and completion handler patterns.

```swift
Task {
  do {
    let paywallViewController = try await Superwall.shared.getPaywall(
      forPlacement: "premium_feature",
      params: ["source": "settings"],
      delegate: self,
      onCustomCallback: { callback in
        switch callback.name {
        case "validate_email":
          return .success(data: ["validated": true])
        default:
          return .failure()
        }
      }
    )
    
    present(paywallViewController, animated: true)
  } catch let reason as PaywallSkippedReason {
    print("Paywall skipped: \(reason)")
  } catch {
    print("Error getting paywall: \(error)")
  }
}
```

```swift
Superwall.shared.getPaywall(
  forPlacement: "premium_feature",
  delegate: self,
  onCustomCallback: { callback in
    .success(data: ["callback": callback.name])
  }
) { paywall, skippedReason, error in
  if let paywall = paywall {
    present(paywall, animated: true)
  } else if let reason = skippedReason {
    print("Paywall skipped: \(reason)")
  } else if let error = error {
    print("Error: \(error)")
  }
}
```

--------------------------------

### Debug Configuration Example

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Example of a verbose configuration for development and debugging purposes.

```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
  )
}
```

--------------------------------

### Initialize Superwall in iOS

Source: https://superwall.com/docs/ios/quickstart/configure

Examples for configuring the Superwall SDK in various iOS application entry points.

```swift
// AppDelegate.swift

import UIKit
import SuperwallKit

@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    Superwall.configure(apiKey: "MY_API_KEY") // Replace this with your API Key
    return true
  }
}
```

```swift
// App.swift

import SwiftUI
import SuperwallKit

@main
struct MyApp: App {
  init() {
    let apiKey = "MY_API_KEY" // Replace this with your API Key
    Superwall.configure(apiKey: apiKey)
  }

  // etc...
```

```objective-c
// AppDelegate.m

@import SuperwallKit;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Initialize the Superwall service.
    [Superwall configureWithApiKey:@"MY_API_KEY"];
    return YES;
}
```

--------------------------------

### Configure SuperwallOptions

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Basic setup for customizing paywall behavior, logging, and SDK event collection.

```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

// Control SDK event collection
options.eventTrackingBehavior = .superwallOnly

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

--------------------------------

### Refresh Configuration Usage

Source: https://superwall.com/docs/ios/sdk-reference/refreshConfiguration

Examples of how to trigger a configuration refresh in Swift using async/await or a completion block.

```swift
Task {
  await Superwall.shared.refreshConfiguration()
  // Updated paywalls will be used on the next presentation
}
```

```swift
Superwall.shared.refreshConfiguration {
  // Handle post-refresh work here
}
```

--------------------------------

### Handle purchase results

Source: https://superwall.com/docs/ios/guides/direct-purchasing

An example implementation showing how to handle different PurchaseResult cases, such as cancellation, success, or failure.

```swift
func purchase(_ product: StoreProduct) async throws {
    let result = await Superwall.shared.purchase(product)
    
    switch result {
    case .cancelled:
        throw CaffeinePalStoreFrontError.cancelled
    case .purchased:
        // In `handleSuperwallEvent` delegate method, we'll check if an espresso recipe was
        // Purchased and if it was, we'll add it to the purchased drinks set.
        print("Purchased product \(product.productIdentifier)")
    case .pending:
        throw CaffeinePalStoreFrontError.pending
    case .failed(let error):
        throw error
    }
}
```

--------------------------------

### Setting Multiple User Attributes

Source: https://superwall.com/docs/ios/sdk-reference/setUserAttributes

Example of setting a dictionary of various attribute types.

```swift
let attributes: [String: Any] = [
  "name": "John Doe",
  "email": "john@example.com",
  "plan": "premium",
  "signUpDate": Date(),
  "profilePicUrl": URL(string: "https://example.com/pic.jpg")!,
  "isVip": true,
  "loginCount": 42
]

Superwall.shared.setUserAttributes(attributes)
```

--------------------------------

### SuperwallEvent Handling

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallEvent

Example of how to handle Superwall events within the SuperwallDelegate implementation.

```APIDOC
## SuperwallEvent Handling

### Description
Events are received via the `SuperwallDelegate.handleSuperwallEvent(withInfo:)` method. This allows developers to intercept and process specific event types such as permission requests or paywall interactions.

### Method
`handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo)`

### Parameters
- **eventInfo** (SuperwallEventInfo) - Required - Contains the event type and associated parameters.

### Usage Example
```swift
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
  switch eventInfo.event {
  case .permissionRequested(let permission, let paywallId):
    logger.info("Prompting \(permission) from paywall \(paywallId)")
  case .permissionGranted(let permission, _):
    analytics.track("permission_granted", properties: eventInfo.params)
  case .permissionDenied(let permission, _):
    showSettingsNudge(for: permission)
  default:
    break
  }
}
```
```

--------------------------------

### Handling Monthly Billing Plans in PurchaseController

Source: https://superwall.com/docs/ios/sdk-reference/PurchaseController

Example implementation for passing billing plan options to StoreKit 2 when performing a purchase.

```swift
func purchase(product: StoreProduct) async -> PurchaseResult {
  guard let sk2Product = product.sk2Product else {
    return .cancelled
  }

  var options: Set<StoreKit.Product.PurchaseOption> = []

  if let token = product.introOfferToken {
    options.insert(.introductoryOfferEligibility(compactJWS: token.token))
  }

  if #available(iOS 26.4, macOS 26.4, tvOS 26.4, watchOS 26.4, visionOS 26.4, *),
    let billingPlanType = product.billingPlanType {
    let storeKitBillingPlan: StoreKit.Product.SubscriptionInfo.BillingPlanType

    switch billingPlanType {
    case .upFront:
      storeKitBillingPlan = .upFront
    case .monthly:
      storeKitBillingPlan = .monthly
    }

    options.insert(.billingPlanType(storeKitBillingPlan))
  }

  do {
    let result = try await sk2Product.purchase(options: options)

    switch result {
    case .success(.verified(let transaction)):
      await transaction.finish()
      return .purchased
    case .success(.unverified(_, let error)):
      return .failed(error)
    case .pending:
      return .pending
    case .userCancelled:
      return .cancelled
    @unknown default:
      return .cancelled
    }
  } catch {
    return .failed(error)
  }
}
```

--------------------------------

### Confirm All Assignments Usage

Source: https://superwall.com/docs/ios/sdk-reference/confirmAllAssignments

Examples showing how to retrieve experiment assignments using both modern concurrency and completion handlers.

```swift
let assignments = await Superwall.shared.confirmAllAssignments()

print("User has \(assignments.count) experiment assignments")

for assignment in assignments {
  print("Experiment: \(assignment.experimentId), Variant: \(assignment.variant)")
}
```

```swift
Superwall.shared.confirmAllAssignments { assignments in
  print("Confirmed \(assignments.count) assignments")
  
  // Process assignments
  for assignment in assignments {
    // Handle assignment
  }
}
```

--------------------------------

### Monitor Paywall Preload Events in Swift

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallEvent

Use this switch statement to track the start and completion of background paywall preloading using the eventInfo object.

```swift
switch eventInfo.event {
case .paywallPreloadStart(let count):
  Metrics.shared.begin("paywall_preload", metadata: ["count": count])
case .paywallPreloadComplete(let count):
  Metrics.shared.end("paywall_preload", metadata: ["count": count])
default:
  break
}
```

--------------------------------

### Configure Superwall with Options and Completion

Source: https://superwall.com/docs/ios/sdk-reference/configure

Initialize the SDK with custom options and a completion handler to confirm successful configuration.

```swift
let options = SuperwallOptions()
options.paywalls.shouldShowPurchaseFailureAlert = false

Superwall.configure(
  apiKey: "pk_your_api_key",
  options: options
) {
  print("Superwall configured successfully")
}
```

--------------------------------

### Get Device Attributes

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Retrieve current device attributes for debugging or filtering.

```swift
let deviceAttributes = await Superwall.shared.getDeviceAttributes()
// Use in audience filters or for debugging
print("Device attributes: \(deviceAttributes)")
```

--------------------------------

### Superwall.configure(apiKey:purchaseController:options:completion:)

Source: https://superwall.com/docs/ios/sdk-reference/configure

Initializes the Superwall SDK instance. This method should be called once to set up the SDK for use throughout the application.

```APIDOC
## Superwall.configure(apiKey:purchaseController:options:completion:)

### Description
Configures the shared instance of Superwall with your API key and optional configurations, making it ready for use throughout your app.

### Signature
```swift
public static func configure(
  apiKey: String,
  purchaseController: PurchaseController? = nil,
  options: SuperwallOptions? = nil,
  completion: (() -> Void)? = nil
) -> Superwall
```

### Parameters
- **apiKey** (String) - Required - Your Public API Key from the Superwall dashboard settings.
- **purchaseController** (PurchaseController?) - Optional - Optional object for handling all subscription-related logic yourself. If nil, Superwall handles subscription logic. Default: nil.
- **options** (SuperwallOptions?) - Optional - Optional configuration object for customizing paywall appearance and behavior. Default: nil.
- **completion** (() -> Void)? - Optional - Optional completion handler called when Superwall finishes configuring. Default: nil.

### Returns
Returns the configured Superwall instance.

### Usage
```swift
Superwall.configure(apiKey: "pk_your_api_key")
```
```

--------------------------------

### Basic Superwall Configuration

Source: https://superwall.com/docs/ios/sdk-reference/configure

Initialize the SDK using only the required API key.

```swift
Superwall.configure(apiKey: "pk_your_api_key")
```

--------------------------------

### Get Device Attributes Signature

Source: https://superwall.com/docs/ios/sdk-reference/getDeviceAttributes

The method signature for retrieving device attributes asynchronously.

```swift
public func getDeviceAttributes() async -> [String: Any]
```

--------------------------------

### Real-world Profile Update

Source: https://superwall.com/docs/ios/sdk-reference/setUserAttributes

Example of updating user attributes within a profile update function.

```swift
func updateUserProfile(user: User) {
  Superwall.shared.setUserAttributes([
    "name": user.displayName,
    "avatar": user.avatarURL,
    "preferences": user.notificationPreferences,
    "lastUpdated": Date()
  ])
}
```

--------------------------------

### Configure Superwall with Purchase Options

Source: https://superwall.com/docs/ios/guides/configuring

Initializes the SDK with custom options to enable web purchase confirmation alerts.

```objective-c
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.shouldShowWebPurchaseConfirmationAlert = true;

[Superwall
  configureWithApiKey:@"MY_API_KEY"
  purchaseController:nil
  options:options
  completion:nil
];
```

--------------------------------

### Get Subscription Status

Source: https://superwall.com/docs/ios/sdk-reference/subscriptionStatus

Retrieve and handle the current subscription status using a switch statement.

```swift
let status = Superwall.shared.subscriptionStatus
switch status {
case .unknown:
  print("Subscription status unknown")
case .active(let entitlements):
  print("User has active entitlements: \(entitlements)")
case .inactive:
  print("User has no active subscription")
}
```

--------------------------------

### Handle Purchased Products in Objective-C

Source: https://superwall.com/docs/ios/guides/advanced/viewing-purchased-products

Implement the SWKSuperwallDelegate protocol and configure the Superwall SDK within the AppDelegate.

```objective-c
// SWDelegate.h...
#import <Foundation/Foundation.h>
@import SuperwallKit;

NS_ASSUME_NONNULL_BEGIN

@interface SWDelegate : NSObject <SWKSuperwallDelegate>

@end

NS_ASSUME_NONNULL_END

// SWDelegate.m...
@implementation SWDelegate

- (void)handleSuperwallEventWithInfo:(SWKSuperwallEventInfo *)eventInfo {
  switch(eventInfo.event) {
    case SWKSuperwallEventTransactionComplete:
      NSLog(@"Transaction complete: %@", eventInfo.params[@"primary_product_id"]);
  }
}

// In AppDelegate.m...
#import "AppDelegate.h"
#import "SWDelegate.h"
@import SuperwallKit;

@interface AppDelegate ()

@property (strong, nonatomic) SWDelegate *delegate;

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    self.delegate = [SWDelegate new];
    [Superwall configureWithApiKey:@"my_api_key"];
    [Superwall sharedInstance].delegate = self.delegate;

    return YES;
}
```

--------------------------------

### Add SuperwallKit to Podfile

Source: https://superwall.com/docs/ios/quickstart/install

The dependency declaration required in your Podfile to install SuperwallKit via CocoaPods.

```ruby
pod 'SuperwallKit', '< 5.0.0'
```

--------------------------------

### Configure Superwall and RevenueCat

Source: https://superwall.com/docs/ios/guides/using-revenuecat

Initializes both SDKs with matching user identifiers when using RevenueCat's observer mode.

```swift
Superwall.configure(apiKey: "superwall_public_key")
Superwall.shared.identify(userId: user.identifier)
Purchases.configure(with:
  .builder(withAPIKey: "revcat_public_key")
  .with(purchasesAreCompletedBy: .myApp, storeKitVersion: .storeKit1/.storeKit2)
  .with(appUserID: user.identifier)
  .build()
)
```

--------------------------------

### Configure Superwall SDK with Options

Source: https://superwall.com/docs/ios/guides/configuring

Initialize the Superwall SDK with custom options, such as disabling automatic paywall preloading.

```swift
let options = SuperwallOptions()
options.paywalls.shouldPreload = false

Superwall.configure(apiKey: "MY_API_KEY", options: options)
```

```objective-c
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.shouldPreload = false;

[Superwall
  configureWithApiKey:@"MY_API_KEY"
  purchaseController:nil
  options:options
  completion:nil
];
```

--------------------------------

### Configure and Access Superwall

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Initialize the SDK and register placements throughout the application.

```swift
Superwall.configure(apiKey: "pk_your_api_key")
```

```swift
Superwall.shared.register(placement: "feature_access") {
  // Feature code here
}
```

--------------------------------

### Retrieve CustomerInfo inside a Task

Source: https://superwall.com/docs/ios/sdk-reference/getCustomerInfo

Example of calling the async method within a structured concurrency Task.

```swift
Task {
  let customerInfo = await Superwall.shared.getCustomerInfo()
  
  // Process customer info
  await processCustomerInfo(customerInfo)
}
```

--------------------------------

### Configure Superwall with Custom Purchase Controller

Source: https://superwall.com/docs/ios/sdk-reference/configure

Initialize the SDK while providing a custom object to handle subscription-related logic.

```swift
Superwall.configure(
  apiKey: "pk_your_api_key",
  purchaseController: MyPurchaseController()
)
```

--------------------------------

### app_install

Source: https://superwall.com/docs/ios/guides/3rd-party-analytics/tracking-analytics

The app_install event is triggered when the Superwall SDK is configured for the first time.

```APIDOC
## app_install

### Description
Triggered when the SDK is configured for the first time.

### Parameters
- **is_superwall** (Bool) - Indicates if the event is from Superwall.
- **app_session_id** (String) - The unique identifier for the current app session.
- **using_purchase_controller** (Bool) - Indicates if a custom purchase controller is being used.
```

--------------------------------

### Configure Superwall with PurchaseController

Source: https://superwall.com/docs/ios/guides/custom-store-products

Initialize the Superwall SDK by passing a custom PurchaseController instance during configuration.

```swift
let purchaseController = CustomStorePurchaseController()

Superwall.configure(
  apiKey: "MY_API_KEY",
  purchaseController: purchaseController
)
```

--------------------------------

### Identification in Login Flow

Source: https://superwall.com/docs/ios/sdk-reference/identify

Example of calling identify within a login handler, followed by setting additional user attributes.

```swift
func userDidLogin(user: User) {
  Superwall.shared.identify(userId: user.id)
  
  // Set additional user attributes
  Superwall.shared.setUserAttributes([
    "email": user.email,
    "plan": user.subscriptionPlan,
    "signUpDate": user.createdAt
  ])
}
```

--------------------------------

### Configure Product Overrides

Source: https://superwall.com/docs/ios/guides/advanced-configuration

Dynamically substitute products on paywalls by providing overrides during Superwall configuration.

```swift
// Configure product overrides when setting up Superwall
let paywallOptions = PaywallOptions()
paywallOptions.overrideProductsByName = [
  "primary": "com.example.premium_monthly_promo",
  "secondary": "com.example.premium_annual_promo",
  "tertiary": "com.example.premium_lifetime"
]

Superwall.configure(
  apiKey: "MY_API_KEY",
  purchaseController: MyPurchaseController.shared,
  options: paywallOptions
)
```

```objective-c
// Configure product overrides when setting up Superwall
SWKPaywallOptions *paywallOptions = [[SWKPaywallOptions alloc] init];
paywallOptions.overrideProductsByName = @{
  @"primary": @"com.example.premium_monthly_promo",
  @"secondary": @"com.example.premium_annual_promo", 
  @"tertiary": @"com.example.premium_lifetime"
};

[Superwall configureWithApiKey:@"MY_API_KEY" 
              purchaseController:[MyPurchaseController sharedInstance]
                        options:paywallOptions 
                     completion:nil];
```

--------------------------------

### Purchase a fetched product

Source: https://superwall.com/docs/ios/guides/direct-purchasing

Initiate the purchase flow for a product previously fetched via the SDK.

```swift
let result = await Superwall.shared.purchase(caffeineSub)
```

--------------------------------

### setUserAttributes(_ attributes: [String: Any?])

Source: https://superwall.com/docs/ios/sdk-reference/setUserAttributes

Sets custom user attributes for the current user. Attributes are used for paywall personalization and analytics. Keys starting with '$' are reserved and ignored. Arrays and dictionaries are not supported as values.

```APIDOC
## setUserAttributes(_ attributes: [String: Any?])

### Description
Sets custom user attributes that can be used in paywall personalization, audience filters, and analytics on the Superwall dashboard. If an attribute already exists, its value will be overwritten.

### Signature
`public func setUserAttributes(_ attributes: [String: Any?])`

### Parameters
- **attributes** ([String: Any?]) - Required - A dictionary of custom attributes to store for the user. Values can be any JSON encodable value, URLs, or Dates.

### Returns
- **Void**

### Usage
```swift
let attributes: [String: Any] = [
  "name": "John Doe",
  "email": "john@example.com",
  "plan": "premium",
  "signUpDate": Date(),
  "profilePicUrl": URL(string: "https://example.com/pic.jpg")!,
  "isVip": true,
  "loginCount": 42
]

Superwall.shared.setUserAttributes(attributes)
```
```

--------------------------------

### Handle Purchased Products in Swift

Source: https://superwall.com/docs/ios/guides/advanced/viewing-purchased-products

Implement the SuperwallDelegate to switch on transaction events and configure the Superwall SDK in your App struct.

```swift
class SWDelegate: SuperwallDelegate {
  func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
    switch eventInfo.event {
    case .transactionComplete(_, let product, _, _):
      print("Transaction complete: product: \(product.productIdentifier)")
    case .subscriptionStart(let product, _):
      print("Subscription start: product: \(product.productIdentifier)")
    case .freeTrialStart(let product, _):
      print("Free trial start: product: \(product.productIdentifier)")
    case .transactionRestore(_, _):
      print("Transaction restored")
    case .nonRecurringProductPurchase(let product, _):
      print("Consumable product purchased: \(product.id)")
    default:
      print("Unhandled event.")
    }
  }
}

@main
struct Caffeine_PalApp: App {
  @State private var swDelegate: SWDelegate = .init()

  init() {
    Superwall.configure(apiKey: "my_api_key")
    Superwall.shared.delegate = swDelegate
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}
```

--------------------------------

### restoreStart

Source: https://superwall.com/docs/ios/guides/3rd-party-analytics/tracking-analytics

This event is triggered when a user initiates a restore process within the application.

```APIDOC
## restoreStart

### Description
Triggered when a restore process is initiated by the user.

### Parameters
- None
```

--------------------------------

### paywallProductsLoad_start

Source: https://superwall.com/docs/ios/guides/3rd-party-analytics/tracking-analytics

This event is triggered when the request to load a paywall's products begins.

```APIDOC
## paywallProductsLoad_start

### Description
This event is triggered when the request to load a paywall's products begins. It functions similarly to the `paywallResponseLoad_start` event.
```

--------------------------------

### Implementing a PurchaseController

Source: https://superwall.com/docs/ios/guides/advanced-configuration

Create a class conforming to the PurchaseController protocol to handle purchasing and restoration logic manually.

```swift
// MyPurchaseController.swift

import SuperwallKit
import StoreKit

final class MyPurchaseController: PurchaseController {
  static let shared = MyPurchaseController()

  // 1
  func purchase(product: StoreProduct) async -> PurchaseResult {
    // Use StoreKit, RevenueCat, or your own billing system to purchase...
    // If `product.sk1Product` and `product.sk2Product` are both nil,
    // this is a custom product that should be handled externally.
    // Send Superwall the result.
    return .purchased // .cancelled,  .pending, .failed(Error)
  }

  func restorePurchases() async -> RestorationResult {
    // Use StoreKit or some other SDK to restore...
    // Send Superwall the result.
    return .restored // Or failed(error)
  }
}
```

--------------------------------

### Configure Superwall with PurchaseController

Source: https://superwall.com/docs/ios/guides/using-revenuecat

Initializes the RCPurchaseController and passes it to the Superwall configuration.

```swift
let purchaseController = RCPurchaseController()

Superwall.configure(
  apiKey: "MY_API_KEY",
  purchaseController: purchaseController
)
```

--------------------------------

### Configure PaywallOptions in Swift

Source: https://superwall.com/docs/ios/sdk-reference/PaywallOptions

Initialize and configure PaywallOptions to customize paywall behavior, then pass it to SuperwallOptions during SDK configuration.

```swift
let paywallOptions = PaywallOptions()
paywallOptions.isHapticFeedbackEnabled = true
paywallOptions.shouldShowPurchaseFailureAlert = false
paywallOptions.shouldPreload = true
paywallOptions.automaticallyDismiss = true
paywallOptions.transactionBackgroundView = .spinner
paywallOptions.overrideProductsByName = [
  "primary": "com.example.premium_monthly",
  "tertiary": "com.example.premium_annual"
]
paywallOptions.shouldShowWebRestorationAlert = true
paywallOptions.notificationPermissionsDenied = {
  let n = PaywallOptions.NotificationPermissionsDenied()
  n.title = "Notification Permissions Denied"
  n.message = "Please enable notification permissions from the Settings app so we can notify you when your free trial ends."
  n.actionButtonTitle = "Open Settings"
  n.closeButtonTitle = "Not now"
  return n
}()

let options = SuperwallOptions()
options.paywalls = paywallOptions

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

--------------------------------

### Configure Superwall in iOS Applications

Source: https://superwall.com/docs/ios/guides/advanced-configuration

Initialize the Superwall SDK during application startup using the provided API key and a custom purchase controller.

```swift
// AppDelegate.swift

import UIKit
import SuperwallKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    Superwall.configure(
      apiKey: "MY_API_KEY",
      purchaseController: MyPurchaseController.shared // <- Handle purchases on your own
    )

    return true
  }
}
```

```swift
@main
struct MyApp: App {

  init() {
    Superwall.configure(
      apiKey: "MY_API_KEY",
      purchaseController: MyPurchaseController.shared // <- Handle purchases on your own
    )
  }
  
  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}
```

```objective-c
// AppDelegate.m

@import SuperwallKit;

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
  // Override point for customization after application launch.
  [Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:[MyPurchaseController sharedInstance] options:nil completion:nil];
  return YES;
}
```

--------------------------------

### Configure PaywallOptions

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Customizes presentation, transaction behavior, and product overrides for paywalls.

```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
```

--------------------------------

### Passing Intro Offer Eligibility Token in PurchaseController

Source: https://superwall.com/docs/ios/guides/intro-offer-eligibility-override

Use the introOfferToken from the product to create a PurchaseOption for StoreKit when implementing a custom PurchaseController.

```swift
func purchase(product: StoreProduct) async -> PurchaseResult {
  guard let sk2Product = product.sk2Product else {
    return .cancelled
  }

  var options: Set<StoreKit.Product.PurchaseOption> = []

  // Grab the introOfferToken
  if let introOfferToken = product.introOfferToken {
    // Add it as a PurchaseOption
    options.insert(.introductoryOfferEligibility(compactJWS: introOfferToken.token))
  }

  // Pass it in to the StoreKit purchase function
  let result = try await sk2Product.purchase(options: options)

  // etc...
}
```

--------------------------------

### Manual paywall implementation without Superwall

Source: https://superwall.com/docs/ios/quickstart/feature-gating

This approach requires manual subscription checks and paywall presentation logic within the application code.

```swift
func pressedWorkoutButton() {
  if (user.hasActiveSubscription) {
    navigation.startWorkout()
  } else {
    navigation.presentPaywall() { result in
      if (result) {
        navigation.startWorkout()
      } else {
        // user didn't pay, developer decides what to do
      }
    }
  }
}
```

```objective-c
- (void)pressedWorkoutButton {
  if (user.hasActiveSubscription) {
    [navigation startWorkout];
  } else {
    [navigation presentPaywallWithCompletion:^(BOOL result) {
      if (result) {
        [navigation startWorkout];
      } else {
        // user didn't pay, developer decides what to do
      }
    }];
  }
}
```

--------------------------------

### Implement PurchaseController for iOS

Source: https://superwall.com/docs/ios/guides/advanced-configuration

A complete implementation of the PurchaseController protocol to handle subscription synchronization, product purchases, and restoration logic.

```swift
import StoreKit
import SuperwallKit

enum PurchaseControllerError: LocalizedError {
case customProductNotHandled(productId: String)

var errorDescription: String? {
  switch self {
  case .customProductNotHandled(let productId):
    return "Custom product \(productId) must be handled by your external billing system."
  }
}
}

final class SWPurchaseController: PurchaseController {
  // MARK: Sync Subscription Status
  /// Makes sure that Superwall knows the customer's subscription status by
  /// changing `Superwall.shared.subscriptionStatus`
  func syncSubscriptionStatus() async {
    /// Every time the customer info changes, the subscription status should be updated.
    for await _ in Superwall.shared.customerInfoStream {
      var products: Set<String> = []
      for await verificationResult in Transaction.currentEntitlements {
        switch verificationResult {
        case .verified(let transaction):
          products.insert(transaction.productID)
        case .unverified:
          break
        }
      }

      let activeDeviceEntitlements = Superwall.shared.entitlements.byProductIds(products)
      let activeWebEntitlements = Superwall.shared.entitlements.web
      let allActiveEntitlements = activeDeviceEntitlements.union(activeWebEntitlements)

      await MainActor.run {
        Superwall.shared.subscriptionStatus = .active(allActiveEntitlements)
      }
    }
  }

  // MARK: Handle Purchases
  /// For App Store-backed products, delegate to `Superwall.shared.purchase(...)`.
  /// Custom products from Superwall paywalls must be handled in your
  /// external billing system using `product.productIdentifier`.
  func purchase(product: StoreProduct) async -> PurchaseResult {
    if product.sk1Product != nil || product.sk2Product != nil {
      return await Superwall.shared.purchase(product)
    }

    // Replace this with your own external billing implementation.
    return .failed(
      PurchaseControllerError.customProductNotHandled(
        productId: product.productIdentifier
      )
    )
  }

  // MARK: Handle Restores
  /// Makes a restore with Superwall and returns its result after syncing subscription status.
  /// This gets called when someone tries to restore purchases on one of your paywalls.
  func restorePurchases() async -> RestorationResult {
    let result = await Superwall.shared.restorePurchases()
    return result
  }
}
```

--------------------------------

### Set up SuperwallDelegate

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallDelegate

Assign the delegate to the Superwall shared instance within a UIViewController.

```swift
class ViewController: UIViewController, SuperwallDelegate {
  
  override func viewDidLoad() {
    super.viewDidLoad()
    Superwall.shared.delegate = self
  }
}
```

--------------------------------

### Registering Local Resources in Swift

Source: https://superwall.com/docs/ios/guides/local-resources

Configure local resources by assigning a dictionary of resource IDs to URLs or images in SuperwallOptions before calling configure().

```swift
let options = SuperwallOptions()
options.localResources = [
  "hero-image": Bundle.main.url(forResource: "hero", withExtension: "png")!,
  "logo": UIImage(named: "Logo")!,
  "onboarding-video": Bundle.main.url(forResource: "welcome", withExtension: "mp4")!
]

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

--------------------------------

### Configure Superwall Method Signature

Source: https://superwall.com/docs/ios/sdk-reference/configure

The static method signature for initializing the Superwall SDK.

```swift
public static func configure(
  apiKey: String,
  purchaseController: PurchaseController? = nil,
  options: SuperwallOptions? = nil,
  completion: (() -> Void)? = nil
) -> Superwall
```

--------------------------------

### Preload All Paywalls

Source: https://superwall.com/docs/ios/guides/configuring

Trigger the preloading of all available paywalls. Existing preloaded paywalls will not be reloaded.

```swift
Superwall.shared.preloadAllPaywalls()
```

```objective-c
[[Superwall sharedInstance] preloadAllPaywalls];
```

--------------------------------

### Set Delegate and Override Products

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Configure the delegate and override product identifiers.

```swift
Superwall.shared.delegate = self
```

```swift
Superwall.shared.overrideProductsByName = [
  "primary": "produceID_to_replace_primary_product"
]
```

--------------------------------

### Purchase Products via Superwall

Source: https://superwall.com/docs/ios/guides/advanced/direct-purchasing

Use these methods to initiate a purchase for StoreKit 1, StoreKit 2, or Superwall's StoreProduct objects.

```swift
// For StoreKit 1
private func purchase(_ product: SKProduct) async throws -> PurchaseResult {
  return await Superwall.shared.purchase(product)
}

// For StoreKit 2
private func purchase(_ product: StoreKit.Product) async throws -> PurchaseResult {
  return await Superwall.shared.purchase(product)
}

// Superwall's `StoreProduct`
private func purchase(_ product: StoreProduct) async throws -> PurchaseResult {
  return await Superwall.shared.purchase(product)
}
```

--------------------------------

### Import SuperwallKit

Source: https://superwall.com/docs/ios/quickstart/install

Import statements for accessing the SDK in Swift and Objective-C files.

```swift
import SuperwallKit
```

```objective-c
@import SuperwallKit;
```

--------------------------------

### Handle Deep Links on App Launch

Source: https://superwall.com/docs/ios/sdk-reference/handleDeepLink

Implementation for processing deep links during the initial connection of a scene.

```swift
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
  // Handle deep link on app launch
  if let url = connectionOptions.urlContexts.first?.url {
    let handled = Superwall.handleDeepLink(url)
    if !handled {
      handleAppDeepLink(url)
    }
  }
}
```

--------------------------------

### Preload Paywalls for Specific Placements

Source: https://superwall.com/docs/ios/guides/configuring

Manually trigger the preloading of paywalls associated with specific placement identifiers.

```swift
Superwall.shared.preloadPaywalls(forPlacements: ["campaign_trigger"]);
```

```objective-c
NSMutableSet<NSString *> *eventNames = [NSMutableSet set];
[eventNames addObject:@"campaign_trigger"];

[[Superwall sharedInstance] preloadPaywallsForPlacements:placementNames];
```

--------------------------------

### Configure Basic Paywall Presentation Handler

Source: https://superwall.com/docs/ios/sdk-reference/PaywallPresentationHandler

Registers a handler to manage paywall presentation, dismissal, and result handling for a specific placement.

```swift
func registerFeatureWithHandler() {
  let handler = PaywallPresentationHandler()
  
  handler.onPresent { paywallInfo in
    print("Paywall presented: \(paywallInfo.id)")
    // Pause background tasks, analytics, etc.
  }
  
  handler.onWillDismiss { paywallInfo, result in
    print("Paywall will dismiss: \(paywallInfo.id)")
    // Prepare for dismissal, save state, etc.
  }
  
  handler.onDismiss { paywallInfo, result in
    print("Paywall dismissed with result: \(result)")
    
    switch result {
    case .purchased:
      showSuccessMessage()
    case .cancelled:
      showPromotionalOffer()
    case .restored:
      updateUIForActiveSubscription()
    }
  }
  
  Superwall.shared.register(
    placement: "premium_feature",
    params: ["source": "feature_screen"],
    handler: handler
  ) {
    unlockPremiumFeature()
  }
}
```

--------------------------------

### register(placement:params:handler:feature:)

Source: https://superwall.com/docs/ios/sdk-reference/register

Registers a placement to trigger a paywall and execute a gated feature block.

```APIDOC
## register(placement:params:handler:feature:)

### Description
Registers a placement so that when it's added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature.

### Signature
```swift
public func register(
  placement: String,
  params: [String: Any]? = nil,
  handler: PaywallPresentationHandler? = nil,
  feature: @escaping () -> Void
)
```

### Parameters
- **placement** (String) - Required - The name of the placement you wish to register.
- **params** ([String: Any]?) - Optional - Optional parameters to pass with your placement. These can be referenced within audience filters in your campaign. Keys beginning with `$` are reserved for Superwall and will be dropped. Arrays and dictionaries are currently unsupported and will be ignored.
- **handler** (PaywallPresentationHandler?) - Optional - A handler whose functions provide status updates for the paywall lifecycle.
- **feature** (() -> Void) - Optional - An optional completion block representing the gated feature. It is executed based on the paywall's gating mode: called immediately for **Non-Gated**, called after the user subscribes or if already subscribed for **Gated**.
```

--------------------------------

### getCustomerInfo Method Signatures

Source: https://superwall.com/docs/ios/sdk-reference/getCustomerInfo

Available method signatures for retrieving customer information using async/await or completion handlers.

```swift
public func getCustomerInfo() async -> CustomerInfo

public func getCustomerInfo(completion: @escaping (CustomerInfo) -> Void)
```

--------------------------------

### PaywallOptions Configuration

Source: https://superwall.com/docs/ios/sdk-reference/PaywallOptions

Configuring PaywallOptions to customize SDK behavior and passing it to the Superwall configuration.

```APIDOC
## PaywallOptions

### Description
Configures the behavior of paywalls displayed by the Superwall SDK. Instances of this class are assigned to the `paywalls` property of `SuperwallOptions`.

### Properties
- **isHapticFeedbackEnabled** (Bool) - Whether haptic feedback is enabled for paywall interactions.
- **shouldShowPurchaseFailureAlert** (Bool) - Whether to show an alert when a purchase fails.
- **shouldPreload** (Bool) - Whether paywalls should be preloaded.
- **automaticallyDismiss** (Bool) - Whether the paywall should automatically dismiss after a successful purchase.
- **transactionBackgroundView** (PaywallOptions.TransactionBackgroundView) - The view to show during a transaction (e.g., .spinner).
- **overrideProductsByName** ([String: String]) - A dictionary mapping internal product names to App Store product identifiers.
- **shouldShowWebRestorationAlert** (Bool) - Whether to show an alert for web restoration.
- **notificationPermissionsDenied** (PaywallOptions.NotificationPermissionsDenied) - Configuration for the alert shown when notification permissions are denied.
```

--------------------------------

### Retrieve CustomerInfo with Async/Await

Source: https://superwall.com/docs/ios/sdk-reference/getCustomerInfo

Standard usage pattern for fetching customer information using Swift concurrency.

```swift
let customerInfo = await Superwall.shared.getCustomerInfo()

// Use the customer info
print("User has \(customerInfo.subscriptions.count) subscriptions")
print("Active product IDs: \(customerInfo.activeSubscriptionProductIds)")
```

--------------------------------

### Implement CustomStorePurchaseController

Source: https://superwall.com/docs/ios/guides/custom-store-products

Define a class conforming to PurchaseController to handle custom product purchases, restoration, and subscription status synchronization.

```swift
import SuperwallKit

final class CustomStorePurchaseController: PurchaseController {
  func purchase(product: StoreProduct) async -> PurchaseResult {
    if hasStoreKitProduct(product) {
      return await Superwall.shared.purchase(product)
    }

    do {
      let result = try await BillingClient.shared.purchase(
        productIdentifier: product.productIdentifier
      )

      switch result {
      case .purchased:
        await syncSubscriptionStatus()
        return .purchased
      case .pending:
        return .pending
      case .cancelled:
        return .cancelled
      }
    } catch {
      return .failed(error)
    }
  }

  func restorePurchases() async -> RestorationResult {
    do {
      try await BillingClient.shared.restorePurchases()
      await syncSubscriptionStatus()
      return .restored
    } catch {
      return .failed(error)
    }
  }

  private func hasStoreKitProduct(_ product: StoreProduct) -> Bool {
    if product.sk1Product != nil {
      return true
    }

    if #available(iOS 15.0, *), product.sk2Product != nil {
      return true
    }

    return false
  }

  private func syncSubscriptionStatus() async {
    let activeProductIds = await BillingClient.shared.activeProductIdentifiers()
    let entitlements = Superwall.shared.entitlements.byProductIds(activeProductIds)

    await MainActor.run {
      Superwall.shared.subscriptionStatus = entitlements.isEmpty
        ? .inactive
        : .active(entitlements)
    }
  }
}
```

--------------------------------

### Handle Custom Paywall Actions

Source: https://superwall.com/docs/ios/guides/using-superwall-delegate

Respond to custom tap actions defined in your paywall configuration.

```Swift
class SWDelegate: SuperwallDelegate {
  func handleCustomPaywallAction(withName name: String) {
    if name == "showHelpCenter" {
      DispatchQueue.main.asyncAfter(deadline: .now() + 0.33) {
        self.showHelpCenter.toggle()
      }
    }
  }
}
```

```Objective-C
// SWDelegate.h...
#import <Foundation/Foundation.h>
@import SuperwallKit;

NS_ASSUME_NONNULL_BEGIN

@interface SWDelegate : NSObject <SWKSuperwallDelegate>

@end

NS_ASSUME_NONNULL_END

// SWDelegate.m...
#import "SWDelegate.h"

@implementation SWDelegate

- (void)handleCustomPaywallActionWithName:(NSString *)name {
  if ([name isEqualToString:@"showHelpCenter"]) {
   [self showHelpCenter];
  }
}

@end
```

--------------------------------

### Update Swift framework import

Source: https://superwall.com/docs/ios/guides/migrations/migrating-to-v3

Replace the Paywall import with SuperwallKit in Swift files.

```swift
import Paywall
```

```swift
import SuperwallKit
```

--------------------------------

### Execute a direct purchase

Source: https://superwall.com/docs/ios/guides/direct-purchasing

A simple one-line call to initiate a purchase for a given StoreProduct.

```swift
let result = await Superwall.shared.purchase(product)
```

--------------------------------

### Handle purchased products via SuperwallDelegate in React Native

Source: https://superwall.com/docs/ios/guides/advanced/viewing-purchased-products

Use the handleSuperwallPlacement method to listen for transactionComplete events and extract product details from the placement parameters.

```typescript
import {
  PaywallInfo,
  SubscriptionStatus,
  SuperwallDelegate,
  SuperwallPlacementInfo,
  PlacementType,
} from '../../src';

export class MySuperwallDelegate extends SuperwallDelegate {
  handleSuperwallPlacement(placementInfo: SuperwallPlacementInfo) {
    console.log('Handling Superwall placement:', placementInfo);

    switch (placementInfo.placement.type) {
      case PlacementType.transactionComplete:
        const product = placementInfo.params?.["product"];
        if (product) {
          console.log(`Product: ${product}`);
        } else {
          console.log("Product not found in params.");
        }
        break;
      default:
        break;
    }
  }
}

export default function App() {
  const delegate = new MySuperwallDelegate();

  React.useEffect(() => {
    const setupSuperwall = async () => {
      const apiKey =
        Platform.OS === 'ios'
          ? 'ios_api_project_key'
          : 'android_api_project_key';

      Superwall.configure({
        apiKey: apiKey,
      });

      Superwall.shared.setDelegate(delegate);
    };
  }
}
```

--------------------------------

### getCustomerInfo()

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Retrieves the current customer information asynchronously.

```APIDOC
## getCustomerInfo()

### Description
Fetches the latest customer subscription and entitlement information.

### Signature
`func getCustomerInfo() async -> CustomerInfo`
```

--------------------------------

### Superwall.shared.products(for:)

Source: https://superwall.com/docs/ios/guides/advanced/direct-purchasing

Fetches product information from Superwall for a set of product identifiers.

```APIDOC
## Superwall.shared.products(for: identifiers)

### Description
Retrieves a set of `StoreProduct` objects corresponding to the provided product identifiers.

### Parameters
- **identifiers** (Set<String>) - Required - A set of product identifier strings.

### Returns
- **Set<StoreProduct>** - A set of product objects retrieved from Superwall.
```

--------------------------------

### register(placement:)

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Registers a placement to trigger a paywall or feature access.

```APIDOC
## register(placement:)

### Description
Registers a placement to trigger a paywall or execute feature-specific code.

### Signature
`Superwall.shared.register(placement: String, completion: (() -> Void)?)`
```

--------------------------------

### Superwall.shared

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Access the shared instance of the Superwall SDK. Must be called after configure().

```APIDOC
## Superwall.shared

### Description
Provides access to the configured Superwall instance. You must call `configure()` before accessing this property.

### Signature
`public static var shared: Superwall { get }`
```

--------------------------------

### Update Objective-C framework import

Source: https://superwall.com/docs/ios/guides/migrations/migrating-to-v3

Replace the Paywall import with SuperwallKit in Objective-C files.

```objective-c
@import Paywall;
```

```objective-c
@import SuperwallKit;
```

--------------------------------

### Configure StoreKit version

Source: https://superwall.com/docs/ios/guides/migrations/migrating-to-v4

Set the StoreKit version in SuperwallOptions to override the default behavior.

```swift
SuperwallOption.storeKitVersion = .storeKit1
```
Tokens:
Raw