Flow State Listener

FlowStateListener provides several callback functions during the onboarding and restore flows, so the client code can have its own logic accordingly, for example, when the app configuration is ready, the client app can choose to initialize the OData provider, then use it when the flow is done.

open class FlowStateListener {
    open suspend fun onPasscodeUpdated(newCode: CharArray, oldCode: CharArray?) = Unit
    open suspend fun onUnlockWithPasscode(code: CharArray) = Unit
    open suspend fun onAppConfigRetrieved(appConfig: AppConfig) = Unit
    open suspend fun onApplicationReset() = Unit
    open suspend fun onClientPolicyRetrieved(policies: ClientPolicies) = Unit
    open suspend fun onConsentStatusChange(consents: List<Pair<ConsentType, Boolean>>) = Unit
    open suspend fun onApplicationLocked() = Unit
    open suspend fun onUserSwitched(newUser: DeviceUser, oldUser: DeviceUser?) = Unit
    open suspend fun onFlowFinishedWithData(flowName: String?, data: Intent?) = Unit
    open suspend fun onOfflineEncryptionKeyReady(key: String?) = Unit
    open suspend fun onOAuthTokenReady(token: OAuth2Token) = Unit
    open suspend fun onPasscodeForgot(userId: String) = Unit
}

onAppConfigRetrieved

This is called during both the onboarding and restore flows when the app configuration is retrieved from either the activation process or local storage.

onUserSwitched

This is called in the onboarding flow when the passcode is successfully created. At this time, the oldUser is set to null while the newUser is the current user. It is called in the restore flow when the app is unlocked. For a multiple user app, the client app can check the newUser and the oldUser to see if another user login in order to switch the user data if necessary.

onApplicationReset

This will be called in the reset flow before SDK clears the app data, so the client app can clear the user data which is not known to the SDK before SDK performs the internal data clean.

onOAuthTokenReady

This will be called whenever the OAuth token is renewed, even after the client app is unlocked.

onFlowFinishedWithData

This will be only called if the app is unlocked with the timeout flow. When the client app starts a flow with the API of FlowUtil.start, it can pass in a callback to be notified after the flow is done, so the client code can have its own logic to deal with either the success or failure cases. But for the timeout flow, since it's started by the SDK, the client code does not have the chance to pass in the callback, so this onFlowFinishedWithData will be used in such case to notify the client code about the flow success or failure status.

For example, when the client app enables the LockAndWipeService and the timeout flow detects the lock or wipe status, the timeout flow will be canceled and notify the client code with this callback, the client code can use the following code to know the reasons:

override suspend fun onFlowFinishedWithData(flowName: String?, data: Intent?) {
    logger.debug("Finished flow name: $flowName")
    when (flowName) {
        FlowType.Reset.name,
        FlowType.Logout.name,
        FlowType.DeleteRegistration.name -> {
            data?.getDeleteUserId()?.also { user ->
                logger.debug("Delete registration flow finished, deleted user: {}", user)
            } ?: logger.debug("Not delete registration flow.")

            val intent = Intent().apply {
                setClass(context, WelcomeActivity::class.java)
                addFlags(
                    Intent.FLAG_ACTIVITY_CLEAR_TASK or Intent.FLAG_ACTIVITY_NEW_TASK or
                            Intent.FLAG_ACTIVITY_CLEAR_TOP
                )
            }
            context.startActivity(intent)
        }
        //Timeout
        else -> super.onFlowFinishedWithData(flowName, data)
    }
}

onOfflineEncryptionKeyReady

This function is called during both the onboarding and restore flows when the app configuration is in multiple user profile mode. During onboarding, the offline encryption key is retrieved from the server and saved in the user's local secure store. During the restore flow, the key is retrieved from the store and returned by this function. The client app can use this callback to initialize the offline database locally.

onPasscodeForgot

This function lets client code clean user data when users forget their passcodes. This usually occurs when users exceed the retry limit or click the "Forgot Passcode" button on the sign-in screen during the restore flow.

---

Last update: April 11, 2025