Introduction¶
The SAP BTP SDK for Android version 3.1 introduces a new version of the flows component. It's implemented with Kotlin and the latest Google Android architecture components, managing the step fragments in a single activity and navigation with Google's Navigation component, sharing data among steps with View Model and Live Data.
flows2 provides a default implementation for your app's onboarding and restoring scenarios. It handles all the necessary steps during onboarding: getting the application configuration from either the Discovery Service or by scanning a QR code, authenticating users based on the application configuration, and creating and validating passcodes, for example. These scenarios are based on the existing Foundation and Fiori libraries.
Besides the default implementation, there are also extension points that allow client code to provide its own logic, for example providing additional passcode validation rules, encrypting a local business data secure store with the passcode, etc.
At the same time, all the customization options of the UI are still supported, and additional custom code can be added to flows as well. The flows execute the onboarding and restoring scenarios as a sequential step sequence. Custom code can be added using custom steps added by the app developer.
Multiple user support was added in the SAP BTP SDK for Android 3.3. Now, the single code base flow can support both single and multiple user mode.
Refer to the Onboarding Using the Flow Component of the SAP SDK for Android blog post for additional details.
Installation¶
To use the flows component, include the following dependency in your build.gradle.
dependencies {
implementation group: 'com.sap.cloud.android', name: 'flowsv2', version: sdkVersion
}
Flow Types¶
The Flows library currently supports the following scenarios (flow types) for onboarding flows implementation, described below:
- Onboard
- Restore
- Change Passcode
- Reset Client
- Forgot Passcode
- Create New Account
- Timeout Unlock
- Delete Registration
- Logout Scenario
Each flow contains several steps and each step can be either a single step or a nested flow that contains other steps. For example, the activation step inside the onboarding flow is a nested flow: it contains the step to get application configuration from the Discovery Service and the QR scanning step. Step organization makes it easier to extend the flows component.
The 'Forgot Passcode' and 'Create New Account' flows are actually the same as the 'Onboard' flow, but with different constraints. The 'Forgot Passcode' flow requires the user ID context to identify which user forgot their passcode. The 'Create New Account' flow is used in multiple user mode when creating a new account.
The 'Timeout Unlock' flow is the same as the 'Restore' flow, but it is only used internally by flowsv2. flowsv2 will use the topmost activity to start this flow by asking the user to unlock the mobile app with the passcode. Because the activity might be the main business screen of the mobile app, the logic after unlocking the mobile app will be different than the 'Restore' flow. For example, if the user is not using their own session for some reason after unlocking the app, the 'Timeout Unlock' flow provides options to either retry to create a valid session, or terminate the mobile app.
Besides these predefined flows, you can also use the flows component as a framework to create customized flows, as described below.
The Onboard Scenario¶
The onboarding flow contains the following steps:
- End Usage License Agreement: This is a mandatory step. The user must agree to the terms of the EULA to complete the onboarding process. If the client code has more specific logic to handle the end user license agreement, there is also an option to exclude this step from the standard onboarding flow.
- Activation: Activation gets the application configuration from either the Discovery Service, a QR code, or managed configurations. You can skip this step if the client code already provides a complete application configuration from which the flows component can determine how to authenticate users. Refer to 'Activation' in Understanding Flow Capabilities for additional information.
- Authentication: Based on the application configuration, the authentication step will dynamically provide corresponding authentication methods in place to authenticate users: basic, OAuth, SAML, or certificate authentication methods, for example.
- Passcode: After a user is authenticated based on the passcode policy settings for the application, this step will help the user to create a passcode to protect the mobile application. If the passcode policy is not enabled, this step will be skipped and a developer can use the Change Passcode flow to create a passcode using the default passcode policy at a later time.
- Usage Consent: Usage collection is a feature in Foundation that enables the mobile application to collect various kinds of usage information for analysis. This step will be in the onboarding flow if the developer wants this feature. Note that usage data will only be collected with the user's consent.
- Crash Report Consent: The SAP BTP SDK for Android will generate crash information when a critical error occurs. With the user's consent, the crash report can be uploaded for analysis.
The Restore Scenario¶
After onboarding, the next time the mobile application starts it will execute the restore scenario. The restore flow will first unlock the application with either the passcode or fingerprint, if enabled. Then, if the passcode has expired, the change passcode flow is executed.
The flows component will automatically determine whether to use onboarding or restore, so the client code can use the same source code for these two flows.
The Change Passcode Scenario¶
After onboarding, if the user wants to change the current passcode, the change passcode flow can be started. This flow contains three steps: unlock with passcode, set a new passcode, and confirm the new passcode. This flow will also automatically be executed as part of the restore flow if the current passcode has expired.
The Reset Client Scenario¶
There will be cases when the user wants to reset the mobile client, for example if they have forgotten their passcode. When resetting the client, besides the internal status of the flows component, the client might also have something to clear. And after reset the client mobile application might also want to open the launcher screen, so besides calling the flow component for reset, the client mobile application should also have a FlowStateListener defined and provided to the reset flow.
The Delete Registration Scenario¶
This flow deletes a user from the device. When this flow is executed, the registration at the SAP Mobile Services side will be deleted, and the local data on this device will also be removed. To execute this flow, the user must have a valid server session identifying them. This flow is mainly for multiple user mobile apps (see Shared Device Overview. For single user mobile apps, we recommend using the reset flow.
Logout Scenario¶
This flow only works for OAuth or SAML authentication apps. It will remove the session cookies from the system, so that the user must input their user name and password to authenticate when signing into the app after logout.