Presentation Options (UI Layer)#

Presentation Mode#

HaapiUIKitConfigurationBuilder(...)
    .setPresentationMode(.modal) // or .stack
    .build()

.modal (default) — flow enters from the bottom, dismisses to the bottom. Matches iOS sheet semantics; works well when authentication is a discrete task.

.stack — flow enters from the right, dismisses to the left. Matches navigation-controller semantics; works well when authentication is part of a sequence (onboarding, settings change). On iOS below 16.0 or when used from SwiftUI helpers, a back button is rendered with localized label hui_back.

Authenticator Selector Presentation#

HaapiUIKitConfigurationBuilder(...)
    .setAuthenticationSelectionPresentation(.list) // or .tabs
    .build()

.list (default) — vertical scrollable list. Works well for any count of authenticators.

.tabs — tabbed pager with authenticator content under each tab. Works well when there are 2–4 authenticators and each requires distinct rendering.

Polling Cadence#

HaapiUIKitConfigurationBuilder(...)
    .setAutoPollingDuration(3) // seconds
    .build()

Default is 3 seconds. Set to 0 (or a negative value) to disable automatic polling — the framework instead renders a manual “retry” button. Server-provided PollingProperties.interval (in milliseconds) takes precedence. BankID flows fall back to BankID’s recommended 1-second cadence per the BankID QR-code guidelines when no server interval is provided.

Auto-Handle Flow Error Feedback#

HaapiUIKitConfigurationBuilder(...)
    .setShouldAutoHandleFlowErrorFeedback(true) // default
    .build()

true (default) — the framework displays a generic error alert, waits for dismissal, then forwards the error to your HaapiFlowResult / Activity Result handler.

false — the framework interrupts the flow immediately and forwards the error. The host app is responsible for showing user-facing feedback. Choose false when your design system has its own error UI you want to use uniformly.

Confirm Interruption#

HaapiUIKitConfigurationBuilder(...)
    .setShouldConfirmFlowInterruption(true) // default
    .build()

true (default) — when the user presses back or close mid-flow, an AlertDialog asks for confirmation. When the user confirms, the flow tears down silently with no callback to HaapiFlowResult. When the user cancels the prompt, the flow continues.

false — back / close dismisses the flow immediately, no prompt. Use when your design treats authentication as cancellable-at-any-time and a confirmation step adds friction.

External Browser#

HaapiUIKitConfigurationBuilder(...)
    .setUseDefaultExternalBrowser(false) // default → ASWebAuthenticationSession
    .build()

false (default) — launches ASWebAuthenticationSession, which shares cookies with Safari and keeps the user in the app context. Recommended in most cases.

true — launches Safari (or whichever browser the user has set as default). Use when you need cookies to survive across the external leg of the flow and ASWebAuthenticationSession’s cookie sandboxing is in the way.

Presentation Mode#

WidgetConfiguration.Builder(...)
    .setPresentationMode(PresentationMode.MODAL) // or STACK / CUSTOM
    .build()

PresentationMode.MODAL (default) — Activity enters bottom-to-top. Requires the manifest entry to use Theme.Haapi.Ui.Widget.Activity.Modal (or a custom style extending your app theme with windowIsTranslucent = true):

<activity android:name="se.curity.identityserver.haapi.android.ui.widget.HaapiFlowActivity"
          android:theme="@style/Theme.Haapi.Ui.Widget.Activity.Modal" />

PresentationMode.STACK — Activity enters right-to-left, matching standard Android navigation.

PresentationMode.CUSTOM — use this when you want to handle the Activity transitions yourself in your manifest theme.

Authenticator Selector Presentation#

WidgetConfiguration.Builder(...)
    .setAuthenticationSelectionPresentation(
        AuthenticatorSelectionPresentation.LIST // or TABS
    )
    .build()

AuthenticatorSelectionPresentation.LIST (default) — vertical scrollable list. Works well for any count of authenticators.

AuthenticatorSelectionPresentation.TABS — tabbed pager with authenticator content under each tab. Works well when there are 2–4 authenticators and each requires distinct rendering.

Polling Cadence#

WidgetConfiguration.Builder(...)
    .setAutoPollingDuration(10) // seconds
    .build()

Default is 10 seconds. Set to 0 to disable auto-polling and surface a manual retry button instead. Server-provided PollingProperties.interval overrides the configured value when present.

Auto-Handle Flow Error Feedback#

WidgetConfiguration.Builder(...)
    .setShouldAutoHandleFlowErrorFeedback(true) // default
    .build()

true (default) — the framework displays a generic error AlertDialog, waits for dismissal, then forwards the error to your Activity Result handler.

false — the framework interrupts the flow immediately and forwards the error. The host app is responsible for showing user-facing feedback. Choose false when your design system has its own error UI you want to use uniformly.

Confirm Interruption#

WidgetConfiguration.Builder(...)
    .setShouldConfirmInterruptionFlow(true) // default
    .build()

true (default) — when the user presses back or close mid-flow, an AlertDialog asks for confirmation. When the user confirms, the activity finishes with RESULT_CANCELED. When the user cancels the prompt, the flow continues.

false — back / close dismisses the flow immediately, no prompt. Use when your design treats authentication as cancellable-at-any-time and a confirmation step adds friction.

External Browser#

WidgetConfiguration.Builder(...)
    .setUseDefaultExternalBrowser(false) // default → ChromeTab
    .build()

false (default) — launches a Custom Tabs (ChromeTab) session, which keeps the user in the app context and shares cookies with the user’s installed Chrome browser when present. Recommended in most cases.

true — launches the system default browser. Use when you need cookies to survive across the external leg of the flow and Custom Tabs’ cookie sandboxing is in the way.