Native macOS Support
Add Superwall paywalls to a native AppKit or SwiftUI Mac app, configure purchases and Customer Center, and test window presentation and deep links.
SuperwallKit supports native AppKit and SwiftUI Mac apps, including paywalls, embedded views, purchases, Customer Center, and Test Mode. Use the same configuration and placement APIs as on iOS.
Requirements
- SuperwallKit
4.19.0or later, macOS 12 or later, and Xcode 26 (Swift 6.2) or later. - App Store products and signing configured for your Mac app if you use StoreKit purchases. You can also use an external purchase controller or dashboard-configured custom store checkout.
- For sandboxed apps, enable Outgoing Connections (Client) (
com.apple.security.network.client). Add usage descriptions and sandbox entitlements for any camera, microphone, contacts, photos, or location permissions your paywall requests.
Native macOS support is separate from running an iOS app with Mac Catalyst or as a “Designed for iPad” app. See Supported Platforms and Devices.
Set Up the SDK
Install SuperwallKit with Swift Package Manager, selecting version 4.19.0 or later. Configure it at launch, then register placements from your UI:
import SuperwallKit
Superwall.configure(apiKey: "YOUR_PUBLIC_API_KEY")
// Call when the user reaches this feature.
Superwall.shared.register(placement: "campaign_trigger") {
// Unlock the feature after the campaign allows access.
}Forward incoming URLs for dashboard previews, development links, and checkout returns. For example, add this to your SwiftUI root view:
.onOpenURL { url in
Superwall.handleDeepLink(url)
}For a runnable app, see the native Mac example. The example requires macOS 13+; the SDK supports macOS 12+.
Presentation and Embedding
PaywallViewController inherits from NSViewController on macOS. Public presenter parameters and presentedViewController use PlatformViewController, an alias for NSViewController on macOS and UIViewController on UIKit platforms. PaywallView embeds the native controller in SwiftUI. When embedding it in your own sheet, provide dismiss controls for skipped or failed presentations, since Mac sheets cannot be swiped away. See the Mac example for a complete implementation.
| Presentation style | Native Mac behavior |
|---|---|
| Modal | A 480 × 720 point sheet, reduced to fit the screen. |
| Drawer | A sheet using the configured height percentage, with a 320 point minimum. |
| Fullscreen / fullscreenNoAnimation | Covers the host window's content, with or without animation. |
| Push | Covers the host window's content, sliding from the trailing edge. |
| Popup | A proportionally sized card over a dimmed backdrop. |
The SDK uses the active window. A menu bar app without a presentable window gets a separate paywall window. Overlays follow their host's size and position, and closing the host dismisses the paywall. Escape dismisses modal and drawer sheets; clicking a popup's backdrop dismisses it. Closing follows the normal lifecycle, feature gating, and survey flow.
Fullscreen covers the window's content area; it does not enter macOS full-screen mode. Design for different window aspect ratios. Use device.platform equal to macOS or device.interfaceType equal to mac in audience filters to choose Mac layouts.
Purchases and Customer Center
StoreKit purchases, purchase controllers, restoration, web checkout, and redemption use the shared SDK pipeline. Embedded checkout opens a native sheet; other links open in the user's default browser. Forward checkout return links through Superwall.handleDeepLink(_:) as shown above.
Present the Customer Center with Superwall.shared.presentCustomerCenter(), embed CustomerCenterView, or use CustomerCenterViewController. Subscription management opens the App Store subscriptions page. Refund requests and the native change-plan view require macOS 14; those actions are hidden on older versions. Appearance configuration accepts NSColor on macOS.
Testing and Limitations
- Test Mode provides native starting-entitlement, simulated purchase, and restore sheets.
- Dashboard debug links and
superwall devlinks open a native preview window with paywall selection, locale, and free-trial overrides. The UIKit debugger's template console and local-resource inspector are not included. - Native Macs report
isMac = true. Device identity is an app-scoped UUID persisted in UserDefaults, not Apple's IDFV, and is not sent as IDFV to attribution partners. - MMP install matching is skipped on native macOS because the matching backend supports iOS and Android.
- Screen dimensions are in points. Haptics use the trackpad when supported.
Related
How is this guide?