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 Google Play. The user stays signed in and can continue where they left off after updating.

Requirements

The update screen requires Clerk Android SDK 1.4.0 or later and the com.clerk:clerk-android-ui package. For more information, see Installation.

How minimum versions work

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

The version is the app's versionCode, the whole number Google Play uses to order releases, such as 42. A minimum applies to the app's package name.

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 Android tab.
3. To add an app, select Add Android 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 versionCode that users can keep, such as 42.
6. Enter the Play 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

The Clerk UI library shows an update screen over your app automatically, in its own activity. Users can't dismiss it until they update. Using Android's Back navigation sends the app to the background. The update screen appears again when the user returns.

The update screen shows your app's name and installed version name, such as 4.8.4. The button says Go to Google Play, or Update app if the update URL isn't a Google Play link. 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 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, call withUpdateRequiredViewDisabled() on the options you pass when you initialize Clerk:

package com.example.myclerkapp

import android.app.Application
import com.clerk.api.Clerk
import com.clerk.api.ClerkConfigurationOptions

class MyClerkApp : Application() {
  override fun onCreate() {
    super.onCreate()

    Clerk.initialize(
      context = this,
      publishableKey = "YOUR_PUBLISHABLE_KEY",
      options = ClerkConfigurationOptions().withUpdateRequiredViewDisabled(),
    )
  }
}

Then collect Clerk.appVersionSupportStatus. The following example shows an update screen while the app's version is unsupported:

import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.getValue
import androidx.compose.ui.platform.LocalUriHandler
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import com.clerk.api.Clerk

@Composable
fun AppRoot() {
    val status by Clerk.appVersionSupportStatus.collectAsStateWithLifecycle()
    val uriHandler = LocalUriHandler.current

    if (status.isSupported) {
        HomeScreen()
    } else {
        Column {
            Text("Update required")
            status.updateUrl?.let { updateUrl ->
                Button(onClick = { uriHandler.openUri(updateUrl) }) {
                    Text("Update")
                }
            }
        }
    }
}

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: