Turn your macOS app into a real business with licensing

macOS tutorial: Adding a license key to your Swift app

Here's the actual code. This tutorial walks through the complete setup for adding license key validation to a macOS app built with Swift and SwiftUI.

Step 1: Add the Swift package

In Xcode, go to File → Add Package Dependencies and enter:

https://github.com/licenseseat/licenseseat-swift

Or add it to your Package.swift:

dependencies: [
    .package(url: "https://github.com/licenseseat/licenseseat-swift", from: "0.4.1")
]

The SDK supports macOS 12+, uses async/await, and has zero third-party dependencies.

Step 2: Configure the SDK

In your App struct or AppDelegate, configure LicenseSeat on launch:

import SwiftUI
import LicenseSeat

@main
struct MyApp: App {
    init() {
        LicenseSeatStore.shared.configure(
            apiKey: "ls_live_your_api_key_here",
            productSlug: "your-product-slug"
        ) { config in
            config.autoValidateInterval = 3600      // Re-validate every hour
            config.heartbeatInterval = 300           // Heartbeat every 5 minutes
            config.offlineFallbackMode = .networkOnly // Offline fallback on network errors
            config.maxOfflineDays = 7                // 7-day offline grace period
            config.telemetryEnabled = true           // Anonymous usage stats
            config.debug = false                     // Console logging for development
        }
    }

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

What these settings do:

• apiKey: Your LicenseSeat API key (get it from your dashboard)
• productSlug: Identifies which product this app belongs to
• autoValidateInterval: Recheck the license every hour (3600 seconds)
• heartbeatInterval: Send a ping every 5 minutes for real-time seat tracking
• offlineFallbackMode: .networkOnly falls back to the SDK's cached offline artifact on network errors. In the current Swift SDK, that artifact is still a signed offline token. .always uses offline fallback unconditionally.
• maxOfflineDays: Grace period for offline use (7 days recommended — laptops go offline)
• telemetryEnabled: Collect anonymous usage stats (macOS version, locale, architecture)
• debug: Enable console logging for development

Step 3: Add the license activation window

Here's a complete SwiftUI license activation view:

import SwiftUI
import LicenseSeat

struct LicenseActivationView: View {
    @State private var licenseKey = ""
    @State private var isLoading = false
    @State private var errorMessage: String?
    let onActivated: () -> Void

    var body: some View {
        VStack(spacing: 20) {
            Image(systemName: "key.fill")
                .font(.system(size: 48))
                .foregroundStyle(.secondary)

            Text("Enter your license key")
                .font(.title2)
                .fontWeight(.bold)

            Text("You can find your license key in the email you received after purchase.")
                .foregroundStyle(.secondary)
                .multilineTextAlignment(.center)

            TextField("M4C05-5W1FT-26", text: $licenseKey)
                .textFieldStyle(.roundedBorder)
                .frame(maxWidth: 300)
                .disabled(isLoading)

            Button(action: activate) {
                if isLoading {
                    ProgressView()
                        .controlSize(.small)
                } else {
                    Text("Activate")
                }
            }
            .buttonStyle(.borderedProminent)
            .disabled(licenseKey.trimmingCharacters(in: .whitespaces).isEmpty || isLoading)

            if let error = errorMessage {
                Text(error)
                    .foregroundStyle(.red)
                    .font(.callout)
            }

            Link("Don't have a license? Buy now",
                 destination: URL(string: "https://your-store.com")!)
                .font(.callout)
        }
        .padding(40)
        .frame(width: 420)
    }

    private func activate() {
        isLoading = true
        errorMessage = nil

        Task {
            do {
                try await LicenseSeatStore.shared.activate(licenseKey.trimmingCharacters(in: .whitespaces))
                onActivated()
            } catch let error as APIError {
                errorMessage = switch error.code {
                case "seat_limit_exceeded":
                    "This license is active on too many devices. Deactivate another device first."
                case "license_expired":
                    "This license has expired. Please renew."
                case "license_not_found":
                    "Invalid license key. Please check and try again."
                default:
                    error.message
                }
            } catch {
                errorMessage = "Network error. Please check your connection."
            }
            isLoading = false
        }
    }
}

Step 4: React to license status with SwiftUI

Use the @LicenseState property wrapper to reactively show different UI based on the license status:

import SwiftUI
import LicenseSeat

struct ContentView: View {
    @LicenseState private var status

    var body: some View {
        switch status {
        case .active, .offlineValid:
            MainAppView()
        case .inactive:
            LicenseActivationView { /* refresh */ }
        case .invalid(let message):
            VStack {
                Text("License issue: \(message)")
                Button("Re-enter license key") { /* show activation */ }
            }
        default:
            ProgressView("Checking license...")
        }
    }
}

The @LicenseState wrapper automatically subscribes to license changes. When the license is activated, revoked, or expires, your UI updates instantly.

Step 5: Feature gating with entitlements

Use entitlements for tiers (Free vs Pro) or time-limited update access. The most common pattern for macOS apps: a perpetual license with an updates entitlement that expires after 1 year. Customers keep the app forever but need to renew for new versions.

import LicenseSeat

struct FeatureGatedView: View {
    // Boolean shorthand — true if entitlement is active
    @EntitlementState("pro-features") private var hasPro

    var body: some View {
        if hasPro {
            ProEditorView()
        } else {
            BasicEditorView()
            Button("Upgrade to Pro") { showUpgradePrompt() }
        }
    }
}

// Programmatic check with detailed reason
func checkForUpdates() async {
    let status = LicenseSeatStore.shared.entitlement("updates")

    if status.active {
        // Check for updates via Sparkle 2
        updaterController.checkForUpdates(nil)
    } else {
        switch status.reason {
        case .expired:
            showRenewalPrompt(expiresAt: status.expiresAt)
        case .notFound:
            showUpgradePrompt()
        case .noLicense:
            showActivationPrompt()
        case nil:
            break
        }
    }
}

Step 6: Handling offline use

MacBooks go offline constantly — planes, coffee shops with bad wifi, corporate networks. The current Swift SDK handles this transparently with Ed25519-signed offline tokens. Machine files are the newer preferred offline artifact at the API level, but Swift has not migrated yet:

// Configure offline support
LicenseSeatStore.shared.configure(
    apiKey: "ls_live_...",
    productSlug: "my-mac-app"
) { config in
    config.offlineFallbackMode = .networkOnly  // Fallback on network errors
    config.maxOfflineDays = 7                  // 7-day grace period
}

// The current Swift SDK automatically:
// 1. Caches a signed offline token after activation
// 2. Verifies the token locally when offline (no network needed)
// 3. Checks token expiration, grace period, and clock tampering
// 4. Emits .offlineValid status so your UI can show an "offline" badge
// 5. Re-validates online when connectivity returns

Your users never get blocked. The .offlineValid status lets you show a subtle indicator without disrupting their workflow.

Listening to events (optional)

The SDK emits lifecycle events you can use for analytics, logging, or custom behavior:

import Combine

var cancellables = Set<AnyCancellable>()

// React to specific events
LicenseSeat.shared.eventPublisher(for: "license:revoked")
    .sink { event in
        showRevocationAlert()
    }
    .store(in: &cancellables)

// Track validation for analytics
LicenseSeat.shared.eventPublisher
    .filter { $0.name.hasPrefix("validation:") }
    .sink { event in
        Analytics.track(event.name, properties: event.dictionary ?? [:])
    }
    .store(in: &cancellables)