Activating a license on macOS

When the state is .missingKey, or the app is locked for a reason the customer fixes with another key, show an activation screen. When the customer submits their key, pass it to setLicenseKey(_:), or to activate(key:) of a LicenseObserver:

struct ActivationView: View {
    @EnvironmentObject private var license: LicenseObserver
    @State private var key = ""
    @State private var error: LicenseError?
    @State private var activating = false
 
    var body: some View {
        Form {
            TextField("License key", text: $key)
            if let error { Text(message(for: error)).foregroundStyle(.red) }
            Button("Activate") {
                activating = true
                Task {
                    defer { activating = false }
                    do throws(LicenseError) {
                        try await license.activate(key: key)
                        // The state is now .active: the app unlocks.
                    } catch {
                        self.error = error
                    }
                }
            }
            .disabled(key.isEmpty || activating)
        }
    }
}

setLicenseKey(_:) uses typed throws : it only throws a LicenseError. Write do throws(LicenseError) to get the error typed in catch, or catch let error as LicenseError.

What setLicenseKey(_:) does

On any failure, including the network, it throws a LicenseError, and changes nothing: the stored key, the stored token and the current state stay as they were. A customer whose app is .active and who types a wrong key keeps their working license.

The errors

Branch on error.code, never on error.message, which may change.

func message(for error: LicenseError) -> String {
    switch error.code {
    case .notFound: "This license key wasn't recognized."
    case .licenseExpired: "This license expired."
    case .machineLimitReached: "This license is already used on its maximum number of Macs."
    case .versionNotAllowed: "Your license doesn't include this version."
    case .networkError: "Couldn't reach the license server. Check your connection."
    default: "Activation failed. Try again in a few minutes."
    }
}

The first four are the locking codes: error.isLocking is true for them. They say something about the customer’s license, and the customer needs to do something: another key, a renewal, another version, a free machine. The others say nothing about the license: the customer can try the same key again later.

See handling validation errors for each server error in detail.

.invalidResponse

The server answered, but its token didn’t pass verification. In practice, it means one of:

• The Mac’s clock is wrong. More than 2 hours behind, the token isn’t valid yet; ahead by more than its lifetime, it’s already expired. Ask the customer to set their date and time automatically.
• The public key doesn’t match, like the key of another organization pasted in your code. Every activation fails: you’ll notice it while testing.
• The product id doesn’t match the product the token is for.

error.status is the HTTP status, 200.

The LicenseError

Replacing a key

setLicenseKey(_:) works in every state, not only .missingKey. Use it when the customer:

• enters a new key after their license was refused, in .invalidKey, .expired or .machineLimitReached,
• upgrades to another license, like from a Personal to a Pro license,
• buys a license after a trial license.

On success, the new key and its token replace the old ones. The Mac stays an active machine of the old license on LicenseManager’s side, and keeps one of its places until you or the customer deactivate it.

The SDK has no method to remove the stored key or deactivate the machine. To sign the customer out, see a new computer.

Edge cases

The customer submits twice. Two calls with the same key while the first one runs share one request: both return, or both throw, with the same result.

A key entered while the startup validation still runs. The startup validation’s result is ignored once it comes back: only the new key counts. Simpler: wait for ready() before showing the activation screen, which LicenseObserver does for you with .loading.

A key in lower case. It’s sent as typed, so 7kq2m-… answers not_found when the key is 7KQ2M-…. Generated keys only use upper case letters and digits: if all your keys are generated, upper-case what the customer typed before passing it.

A key with spaces in the middle, like one copied across two lines. Only the spaces around it are removed: clean it up before passing it if your keys never contain spaces.

Activating offline. It’s impossible: the first activation always needs LicenseManager. It throws .networkError, after 30 seconds of retries.