Start Flow

Before Starting a Predefined Flow

Before starting a predefined flow, there are two configurations to be completed.

ActivityLifecycleCallbacks

For most of the features to be used in your mobile app, they will need to know the state of the app, for example whether the app is in the background or not. Therefore, registering an ActivityLifecycleCallbacks to the application is a must.

KOTLIN

//in onCreate of application
registerActivityLifecycleCallbacks(AppLifecycleCallbackHandler.getInstance())

JAVA

//in onCreate of application
registerActivityLifecycleCallbacks(AppLifecycleCallbackHandler.getInstance());

DiscoveryServiceProvider

In the app development stage, you can set the Discovery Service URL for development into DiscoveryServiceProvider when the application starts.

KOTLIN

//in onCreate of application
DiscoveryServiceProvider.set("....")

JAVA

//in onCreate of application
DiscoveryServiceProvider.set("....");

Then, when the onboard flow comes to the Discovery Service activation step, you only need to input the email domain to get the complete application information published to the Discovery Service.

Note

For detailed information about how to configure the Discovery Service, refer to the online help.

APIs to Start a Flow

There are two APIs to start a flow.

@JvmStatic
fun start(activity: Activity, flowContext: FlowContext) {
  ...
}

@JvmStatic
fun start(fragment: Fragment, flowContext: FlowContext) {
    ...
}

Some information will be needed when starting a flow: the application configuration information, customized flow options, etc. This information will be saved into the flowContext.

data class FlowContext(
    /** The predefined flow type*/
    val flowType: FlowType = FlowType.ONBOARDING,
    /** The screen settings */
    val screenSettings: List<ScreenSettings> = listOf(),
    /** The enabled features/service to be initialized by the static initializer */
    val enabledServices: List<KClass<out MobileService>> = listOf(),
    /** The flow action handler */
    val flowActionHandler: FlowActionHandler = FlowActionHandler(),
    /** The flow options to control how to show an `info` type message, which activation method to use*/
    val flowOptions: FlowOptions = FlowOptions(),
    /** The application configuration*/
    val appConfig: AppConfig? = null,
    /**
     * The customized flow. This will override the [flowType] and, if this is set, it will be used as
     * the running flow. The predefined flow contained in [flowType] will be ignored.
     */
    val flow: Flow? = null,
    /** The flow state listener */
    val flowStateListener: FlowStateListener? = null
)

The parameters are:

Parameter	Description
appConfig	The application information that the mobile app uses to talk to mobile services. This is mandatory for onboarding. AppConfig.Builder is provided to build an instance easily.
enabledServices	Specify which features the client application wants to use.
screenSettings	Customize the screens inside the flow.
flowStateListener	Provide customized logic and insert into the flow execution process at certain points.
flowActionHandler	Provide customized logic for certain cases, such as the customize passcode validation logic, for example.
flowOptions	Pass in options, such as specifying which activation method to use. See Flow configuration for details.

Sample client code:

KOTLIN

val flowContext = FlowContext(
    flowType = FlowType.ONBOARDING,
    appConfig = AppConfig.Builder().applicationId("myapp").build(),
    flowStateListener = WizardFlowStateListener())
Flow.start(activity, flowContext)

JAVA

FlowContext flowContext = new FlowContextBuilder()
    .setApplication(prepareAppConfig())
    .setFlowStateListener(new WizardFlowStateListener())
    .build();
Flow.start(activity, flowContext);

After starting a flow, the flowContext will be saved into a FlowContextRegistry. The client code can then get flowContext from FlowContextRegistry at a later time in order to update some of the properties and start another flow. For example:

KOTLIN

val flowContext = FlowContextRegistry.flowContext.copy(flowType = FlowType.RESTORE)
Flow.start(activity, flowContext)

JAVA

FlowContext currentContext = FlowContextRegistry.INSTANCE.getFlowContext();
FlowContext flowContext = new FlowContextBuilder()
        .setApplication(currentContext.getAppConfig())
        .setFlowType(FlowType.CHANGEPASSCODE)
        .setFlowStateListener(currentContext.getFlowStateListener())
        .build();
Flow.start(this, flowContext);

To get the flow execution status, which is either done or canceled, the client activity needs to override the onActivityResult function:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == FlowConstants.FLOW_ACTIVITY_REQUEST_CODE) {
        if (resultCode == Activity.RESULT_OK) {
            //start your main business activity.
            startActivity(Intent(this, MainActivity::class.java))
        } else {
            Snackbar.make(fab, "Flow cancelled.", Snackbar.LENGTH_LONG).show()
        }
    }
}

For more information about enabledServices and screenSettings in FlowContext, see Flow Configuration and flowStateListener and flowActionHandler in Extension Points.

---

Last update: August 12, 2020