Update required
An instance sets a minimum version for an app. Clerk rejects most requests from a build below it, and the SDK covers the app with an update screen that shows the build's version and links to Google Play. Users stay signed in, so they continue where they left off once the build is allowed again.
Sub-features
signed-incovers a signed-in user's app with the update screen on a build below the minimum, showingYour versionandGo to Google Play. Lowering the minimum returns the same user and session.signed-outcovers a signed-out user's app with the update screen too.at-the-minimumleaves a build at the minimum to open as usual.update-appshowsUpdate appinstead ofGo to Google Playwhen the update URL is on another host.
How to get to it (user POV)
- A developer sets a minimum on the Clerk Dashboard's
Native applicationspage, then a user opens a build below it.
Driving it with verify
Preconditions:
The native app settings are off the standard settings, so each test calls
host.useMinimumAppVersion({ minimumVersion, updateUrl }). It registerscom.clerk.e2ewith the application, sets the minimum, and waits for the public environment to show it. When the test ends, the CLI removes the minimum and leaves the registration.Clerk's
native_app_force_updateflag must be on for the instance. It's on globally, and with it off the call fails.The test app's
versionCodeis1and itsversionNameis1.0, ine2e/build.gradle.kts. A minimum is a whole version code, so the spec uses2to block it. The screen shows the version name.Signed in. Run
e2e-tests/bin/control-clerk-android run update-required --grep "signed-in user". The spec signs in with a ticket, sets the minimum to2, and relaunches withkeepStorage: true. It expects1.0andGo to Google Play(screenshotupdate-required). It then lowers the minimum to1, relaunches, and expects the same user and session ID on the home (screenshotsigned-in-after-lowering).Signed out. Run
e2e-tests/bin/control-clerk-android run update-required --grep "signed-out user". The spec sets the minimum to2before the first launch, then expects the update screen and1.0(screenshotupdate-required-signed-out).At the minimum. Run
e2e-tests/bin/control-clerk-android run update-required --grep "at the minimum". The spec sets the minimum to1, signs in with a ticket, and expects the signed-in home with no update screen (screenshotat-the-minimum).Update app. Run
e2e-tests/bin/control-clerk-android run update-required --grep "outside Google Play". The spec sets the minimum to2with an update URL onexample.com, then expectsUpdate appand noGo to Google Play(screenshotupdate-app).Proof.
specs/features/update-required/update-required.e2e.tspasses. The video shows the update screen with1.0, then the home with the same user and session ID.
States a spec cannot reach
| State | Where the app decides | What it takes |
|---|---|---|
Can't update? Get help |
UpdateRequiredView.kt, when supportEmail is not null |
A support email on the instance. The Platform API config has no leaf for it, so a spec cannot set one |
| The screen with no store button | UpdateRequiredView.kt, status.updateUrl?.let |
A minimum with no update URL. Clerk requires one (validateNativeAppMinimum in clerk_go), so only a local patch reaches it |
| An app's own screen instead of Clerk's | withUpdateRequiredViewDisabled() |
A call to it in the test app, and a home that shows appVersionSupportStatus |
| The debug warning that the update screen can't show | UpdateRequiredViewLauncher.kt, warnOnceAppHasMinimum |
A debuggable app that has a minimum and doesn't include com.clerk:clerk-android-ui. The :e2e host includes it, so only a local patch that removes it reaches the warning. It's a log line with no UI |
Gotchas
- A build with no
versionCode, or one below1, is never blocked:AppBuild.frominAppVersionSupport.ktlogs a warning and the SDK skips the check. A spec on such a build would passat the minimumand fail the others. Go to Google PlayandUpdate appopen an outside app, so the spec checks that the text shows and does not tap it.storeButtonTextpicks the label by the update URL's host.- The button's label is a text node beside an unnamed button, so
getByRole('button', { name })does not find it. The spec usesgetByText. - The screen has no test tags of its own, so the spec finds it by its text. A change to that wording changes the spec.
- A minimum applies to the next request or launch. The spec relaunches instead of waiting for a running app to foreground.
- A relaunch restores the cached environment first, and
AppVersionSupport.applyEnvironmentruns for it too. So right after the minimum is lowered, the update screen can open for a moment on the old minimum.UpdateRequiredActivitycloses onceClerk.isInitializedis true and the status is supported, andlandsOn: host.app.signedInwaits through that. Don't assert that the update screen never appears after that relaunch. - The subtitle names the application, which here is the
verify-throwaway-...name. Don't assert on it. - The update screen replaces what the home shows, so the home's locators aren't on screen while it shows. A launch that expects it needs
landsOn.