Flow Lifecycle (UI Layer)#

A complete UIKit pattern — the view controller conforms to HaapiFlowResult, calls HaapiFlow.start(...) on user action, and handles both the success and error outcomes:

extension UIApplication {
    var haapiUIKitApplication: HaapiUIKitApplication {
        guard let appDelegate = delegate as? AppDelegate else {
            fatalError("AppDelegate not configured")
        }
        return appDelegate.haapiUIKitApplication
    }
}

class LoginViewController: UIViewController, HaapiFlowResult {
    @IBAction func signInTapped(_ sender: UIButton) {
        do {
            try HaapiFlow.start(
                from: self,
                haapiUIKitApplication: UIApplication.shared.haapiUIKitApplication,
                haapiDeepLinkManageable: HaapiDeepLinkManager.shared
            )
        } catch {
            // Rare: configuration error prevents flow start
            presentAlert("Could not start authentication: \(error)")
        }
    }

    func didReceiveOAuthTokenModel(_ tokenModel: OAuthTokenModel) {
        // Persist the tokens (Keychain) and navigate to the authenticated state.
        TokenStore.shared.save(tokenModel)
        navigateToHome()
    }

    func didReceiveError(_ error: Error) {
        // Flow-level error after the user started authenticating.
        presentAlert("Authentication failed: \(error)")
    }
}

For SwiftUI hosts, the only difference is the presentation site — the conforming view passes itself to HaapiFlow.start from inside .sheet(isPresented:):

struct ContentView: View, HaapiFlowResult {
    let haapiApplication: HaapiUIKitApplication
    @State private var showingHaapiVC = false

    var body: some View {
        Button("Sign in") { showingHaapiVC = true }
            .sheet(isPresented: $showingHaapiVC) {
                HaapiFlow.start(
                    self,
                    haapiUIKitApplication: haapiApplication,
                    haapiDeepLinkManageable: HaapiDeepLinkManager.shared
                )
            }
    }

    func didReceiveOAuthTokenModel(_ tokenModel: OAuthTokenModel) { /* persist + navigate */ }
    func didReceiveError(_ error: Error) { /* show alert */ }
}

from: — the presenting UIViewController (UIKit) or the conforming view (SwiftUI).

haapiUIKitApplication: — the HaapiUIKitApplication built in AppDelegate from the configured HaapiUIKitConfiguration.

haapiDeepLinkManageable: — HaapiDeepLinkManager.shared handles inbound deep links (universal links / custom schemes) so external-browser-redirect flows complete cleanly.

A complete Activity Result pattern — signInTapped() starts the flow on user action; handleToken() and handleError() are the result-handling counterparts to iOS’s didReceiveOAuthTokenModel / didReceiveError. The launcher property must be declared before the activity reaches STARTED, which is why it lives at class scope rather than inside onCreate:

class MainActivity : AppCompatActivity() {

    // Start the flow on user action
    private fun signInTapped() {
        startHaapiActivityForResult.launch(HaapiFlowActivity.newIntent(this))
    }

    // Persist the tokens (EncryptedSharedPreferences) and navigate
    private fun handleToken(model: OauthModel.Token) {
        TokenStore.save(model)
        navigateToHome()
    }

    // Show a user-facing error after a flow-level failure or interruption
    private fun handleError(message: String) {
        showError(message)
    }

    // Launcher + result callback — registered at property scope so it is
    // ready before the activity reaches STARTED.
    private val startHaapiActivityForResult = registerForActivityResult(
        ActivityResultContracts.StartActivityForResult()
    ) { activityResult ->
        if (activityResult.resultCode == RESULT_OK) {
            when (val model = activityResult.data
                ?.getParcelableExtra(HaapiFlowActivity.className) as? OauthModel) {
                is OauthModel.Token -> handleToken(model)
                is OauthModel.Error -> handleError(model.errorDescription ?: "Unknown error")
                else -> handleError("Unexpected result")
            }
        }
        if (activityResult.resultCode == RESULT_CANCELED) {
            val throwable = activityResult.data
                ?.getSerializableExtra(HaapiFlowActivity.className) as? Throwable
            throwable?.let { handleError("Interrupted: ${it.message}") }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        findViewById<Button>(R.id.button).setOnClickListener { signInTapped() }
    }
}

The legacy startActivityForResult(intent, requestCode) API also works for codebases that haven’t migrated to the Activity Result API; the result-handling switch on OauthModel is identical.