Upgrade — Android UIWidget v5#

The Curity HAAPI Android UIWidget library shipped its v5.0 major release on 2025-11-03, followed by minor releases through 5.4.0 (2026-05-04). This page covers the migration from v4.x to v5.x and highlights the notable additions in each 5.x release.

For the authoritative per-release detail, see the changelog on curity.io/docs/haapi-android-ui/latest/CHANGELOG.html.

Breaking Changes in v5.0#

Kotlin Toolchain#

The framework is now compiled with Kotlin 2.2.20. Backward compatibility is maintained at the Kotlin 2.0 API / language level, so the library remains usable from projects on Kotlin 1.9+.

IdsvrHaapiException Hierarchy (Driver Layer)#

The Driver Layer (consumed transitively by UIWidget) introduced a sealed IdsvrHaapiException hierarchy with two categories:

• IdsvrHaapiException.Retryable — transient errors that can be retried automatically
• IdsvrHaapiException.Unrecoverable — permanent errors requiring intervention

Code that previously caught the older HaapiException types must be re-mapped onto these categories. See Error Handling for the per-category dispatch.

HaapiLogger API (Driver Layer)#

Driver v5.0 removed the deprecated HaapiLogger surfaces:

• Static logging-level configuration properties — replaced by the level setter that takes a LogLevel.
• Logging methods taking tag: String as the first argument — replaced by level-specific calls that take sender: Class<*>.

See Upgrade — HaapiLogger setLogType Migration .

OAuth Error Model#

OauthModel.Error was updated for RFC 6749 compliance (visible through the SDK Layer):

• errorDescription is now optional
• errorUri (optional) has been added

Code that force-reads errorDescription must guard against null.

WebAuthn — ExperimentalWebAuthnApi Removed#

The ExperimentalWebAuthnApi opt-in annotation is gone. WebAuthn methods and properties on WebAuthnRegistrationClientOperationStep and WebAuthnAuthenticationClientOperationStep are now part of the stable API. Remove any @OptIn(ExperimentalWebAuthnApi::class) annotations from your code.

The deprecated WebAuthnRegistrationClientOperationStep.buildParameters(attachment: Attachment, …) overload was removed. Use the overload that takes publicKey: ClientOperationActionModel.WebAuthnRegistration.PublicKey as the first argument instead.

OAuthTokenManager Construction (SDK Layer)#

The OAuthTokenManager direct constructor is removed. Build instances through HaapiAccessorFactory.createForOAuth(…) (or, for the HAAPI flow, createForHaapi(…)). See Creating a HaapiAccessor .

Breaking Changes in v5.1#

HandleableProblemType gained a new case: TooManyAttempts. This is a source-breaking change only if you when on HandleableProblemType without an else branch.

when (problemType) {
    HandleableProblemType.InvalidInputProblem -> …
    HandleableProblemType.TooManyAttempts -> …   // ← new in 5.1
    else -> …
}

IdsvrHaapiException was made Parcelable in v5.1 (along with OAuthUnrecoverableException in the SDK). If your app extends from these types, the Parcelable contract is now required.

Notable Additions Across 5.x#

5.1 (2025-12-15)#

• WidgetConfiguration.Builder.setUsePasskeysBrowserFallback — configures behavior when Passkeys are not supported on the device.
• Improved handling for Too many attempts and Incorrect Credentials problems in FormFragment.
• WebAuthn / Passkeys now uses server-provided residentKey and requireResidentKey values.

5.2 (2026-02-09)#

• Polling cancellation no longer triggers on Intent dispatch.
• Crashes during polling transitions are fixed.
• Driver Layer adds HttpClientRetryableException specializations (SocketStreamInterruptionException, HostConnectionException, HttpRetryException) for cleaner retryable-error classification.
• SDK Layer adds an automatic single-retry for HttpClientRetryableException in HaapiManager and OAuthTokenManager.

5.3 (2026-03-23)#

• BankIdFragment aligned with latest accessibility requirements. New BankIdModel supports the new BankID flow.
• representationType on UIModel.Interaction, UIModel.Problem, UIModel.Operation — exposes the originating HAAPI representation type.
• InteractionValue interface — exposes isRequired, defaulting to true. Custom implementations can override.
• InteractionError interface for items carrying an error.
• FormFragment renders a required-field asterisk on text and select fields during signup, using the configured errorColor.
• SDK Layer adds optional minLength / maxLength to FormField.Text, FormField.Username, FormField.Password.
• Logging migration — setLogType() introduced; static isXxxEnabled flags are deprecated. See Upgrade — HaapiLogger setLogType Migration .

5.4 (2026-05-04)#

• HaapiUI Previewer — debug-only tool to iterate on Theme.Haapi.Ui.Widget.BaseTheme attributes without running a full HAAPI flow. Two surfaces:
  • Compose @Preview via HaapiUIPreviewer for themed screen layouts and component galleries in Android Studio’s preview pane.
  • On-device previewer Activity via HaapiUIPreviewerHostActivity (and HaapiUIPreviewerScenarioListActivity) running real Fragments through the production pipeline.
  • Previewer code lives in src/debug/ and is excluded from release AARs. Public types are marked @ExperimentalHaapiApi and may change in minor releases.
• userCode message style for recovery codes (themed 2-column grid with copy action).
• PollingFragment and BankIdFragment honor the server-provided polling interval from Properties.Polling.interval.
• SDK Layer adds the optional interval on Properties.Polling.

Related Driver / SDK Migrations#

UIWidget composes the Android SDK and Driver layers. The following lower-layer changes affect host apps that touch those types directly:

• DPoP Nonce Auto-Management — DPoPNonceStack direct methods are deprecated in Driver v5.3; the SDK manages the nonce internally.
• HaapiLogger setLogType Migration — logging API migration (v5.3).

Backward Compatibility#

• HaapiAccessorFactory.create was deprecated in v5.1 in favor of createForHaapi / createForOAuth. The old method still compiles in 5.x.
• DPoPNonceStack.pop() / push(value) / peek() are deprecated in favor of get() / set(value) / clear() in Driver v5.3. The class itself is deprecated for removal in the next major.
• HaapiConfigurable.dPoPNonceStack and HaapiConfiguration.dPoPNonceStack are deprecated in SDK v5.3.