Require a minimum app version

You can set a minimum version for each native app in the Clerk Dashboard, for example, when you release a security fix or change an API that older builds depend on. When a user opens a build below that minimum, Clerk rejects most of the app's requests and the SDK covers it with an update screen. The screen has a button that opens your app's page on the App Store. The user stays signed in and can continue where they left off after updating.

Requirements

The update screen requires Clerk iOS SDK 1.7.0 or later and ClerkKitUI. For more information, see Install the SDK.

How minimum versions work

The Clerk SDK sends your app's version and bundle ID with each request. Clerk compares that version with the minimum set for the app.

The version is the app's CFBundleShortVersionString, which users see in the App Store, such as 4.2.1. For iOS minimums, Clerk treats missing numbers as zero, so 4.2 is equivalent to 4.2.0.

The minimum applies to every iOS application with the same bundle ID, including macOS builds.

Set a minimum version

Minimum versions are set per instance, so set them separately for your development and production instances.

1. In the Clerk Dashboard, navigate to the Native applications⁠ page.
2. Select the iOS tab.
3. To add an app, select Add iOS app. To change an existing app, on the right side of the app's row, select the menu icon (...) and select Edit.
4. Enable Minimum app version.
5. Enter the oldest version that users can keep, with up to three dot-separated numbers, such as 4.2.1.
6. Enter the App Store URL that users open to update the app.
7. Select Add application or Update application.

When the app returns to the foreground, the SDK checks whether its version still meets the minimum. If the version is too old, the update screen appears.

To remove a minimum, edit the app, disable Minimum app version, and select Update application. Lowering or removing a minimum lets users on newly allowed versions continue once the SDK checks the change.

What users see

ClerkKitUI shows an update screen over your app automatically. On iOS, it covers every scene in its own window. On macOS, it opens as a sheet on each of your app's main windows. Users can't dismiss it until they update.

The update screen shows your app's name, installed version, minimum version, and a Go to App Store button. It uses the logo from your application's Settings⁠ and the theme set for Clerk views. If you've set a Support email there, it includes a Can't update? Get Help email link.

The screen is available on iOS and macOS. On watchOS, tvOS, and visionOS, show your own update screen. On macOS, the screen doesn't cover panels or windows opened from a menu bar item. If your app runs from the menu bar, show your own update screen.

The SDK applies the minimum it saved from the last environment it loaded, so an outdated app shows the update screen at launch, even when it's offline.

Show your own update screen

To show your own screen instead of Clerk's update screen, set updateRequiredViewEnabled to false when you configure the SDK:

Clerk.configure(
  publishableKey: "YOUR_PUBLISHABLE_KEY",
  options: .init(updateRequiredViewEnabled: false)
)

Then read clerk.appVersionSupportStatus, which updates when the app's status changes. The following example shows an update screen while the app's version is unsupported:

import ClerkKit
import SwiftUI

struct ContentView: View {
  @Environment(Clerk.self) private var clerk
  @Environment(\.openURL) private var openURL

  var body: some View {
    if clerk.appVersionSupportStatus.isSupported {
      HomeView()
    } else {
      VStack(spacing: 16) {
        Text("Update required")
        if let updateURL = clerk.appVersionSupportStatus.updateURL {
          Button("Update") {
            openURL(updateURL)
          }
        }
      }
    }
  }
}

AppVersionSupportStatus

Test a minimum version

Test the update screen on a development instance before you set a minimum on your production instance:

1. In the Clerk Dashboard, navigate to the Native applications⁠ page and set a minimum version higher than your app's current version.
2. Close and reopen your app. The update screen opens.
3. Lower the minimum to your app's current version or older, or disable Minimum app version.
4. Bring your app to the foreground. Once the SDK rechecks the minimum, the update screen closes and the user remains signed in.

Troubleshooting

The update screen doesn't appear

Verify that:

Users see an error message instead of the update screen

Clerk iOS SDK versions 1.0.0 through 1.6.x send the app's version but don't show an update screen. When the app is below the minimum, their requests fail with the message "This version of the app is no longer supported. Update the app to continue."

Release a version of your app that uses Clerk iOS SDK 1.7.0 or later, so that users who later fall below a minimum see the update screen.