Enable Multi-User Mode for Your Android Application

Open the project you previously created using the SAP BTP SDK Wizard for Android.

In Android Studio, on Windows, press Ctrl+N, or, on a Mac, press command+O, and type WelcomeActivity to open WelcomeActivity.java.

On Windows, press Ctrl+F12, or, on a Mac, press command+F12, and type startFlow to move to the startFlow method. For the FlowContext instance, change the parameter of the setMultipleUserMode method from false to true:

FlowContext flowContext = new FlowContextBuilder()
            .setApplication(appConfig)
            .setMultipleUserMode(true)

Notice that the setting will only take effect when the very first user onboards. Once a user is onboarded, this setting will be saved in the local database. All subsequent flows will use the same setting from the database and ignore the one inside flowContext. To change this setting, you need to reset the application to bring up the onboarding process, and the new setting will be updated in the local database after onboarding.

Re-run (quit first) the app and notice that the onboarding process is the same as for single-user mode, except that no biometric authentication screen is shown. After onboarding, put the app in background until the unlock screen appears. In multi-user mode, there is a SWTICH OR ADD USER button at the bottom of the screen.

When the button is clicked, the user list is displayed. You can either select an existing user from the list or click the ADD USER icon at the right top of the screen. This will start the onboarding process for the new user.

For an offline application, you have to enable the Allow Upload of Pending Changes from Previous User option on the server side first. Go to the SAP Mobile Services cockpit and select your application from the application list. Click Mobile Settings Exchange in the assigned features list:

Scroll down to the bottom of the Client Configuration tab and enable the Allow Upload of Pending Changes from Previous User option (remember to click Save to save the change):

Open the project you previously created using the SAP BTP SDK Wizard for Android.

Enable setMultipleUserMode for FlowContext instance same as online app.

In Android Studio, on Windows, press Ctrl+N, or, on a Mac, press command+O, and type OfflineWorkerUtil to open OfflineWorkerUtil.java.

On Windows, press Ctrl+F12, or, on a Mac, press command+F12, and type initializeOffline to move to the initializeOffline method. Notice that for the OfflineODataParameters instance, the value of the setForceUploadOnUserSwitch parameter is set based on the value of runtimeMultipleUserMode. This value is retrieved from the UserSecureStoreDelegate.getInstance().getRuntimeMultipleUserModeAsync() API call.

Unlike the single-user mode scenario, the encryption key is not generated by the client code, but rather retrieved from the server by SDK. Client code can acquire the key using the UserSecureStoreDelegate.getInstance().getOfflineEncryptionKey() API call.

Re-run (quit first) the app. Notice that the onboarding process and add/switch user process are the same as for the online app.

In the offline multi-user mode scenario, when a user makes changes to the local offline store, the changes may not be uploaded to the server when the device is handed over to another user. After the new user clicks Switch Or Add User button to sign in or do onboarding, the pending changes will be uploaded to the server automatically.

If there is an error during synchronization, a screen will be displayed, notifying the user about the synchronization failure.

If synchronization failed because there is no internet connection, a network error screen will be displayed.

If synchronization failed due to a transaction issue, a transaction error screen will be displayed.

The SDK provides a UI component for the two screens and apps can reference the screens to provide error handling.

Open the project you previously created using the SAP BTP SDK Wizard for Android, press Shift twice and type activity_main_business.xml to open res\layout\activity_main_business.xml. To reference the two screens, the layout XML file includes com.sap.cloud.mobile.fiori.onboarding.OfflineNetworkErrorScreen and com.sap.cloud.mobile.fiori.onboarding.OfflineTransactionIssueScreen.

For the Offline Network Error Screen, the client code implements the logic for button click events.

On Windows, press Ctrl+N, or, on a Mac, press command+O, and type MainBusinessActivity to open MainBusinessActivity.java.

On Windows, press Ctrl+F12, or, on a Mac, press command+F12, and type offlineNetworkErrorAction to move to the offlineNetworkErrorAction method. When the network error occurs, make the Offline Network Error Screen visible and provide your logic for the button click event.

For Offline Transaction Issue Screen, the client code needs to set the user information of previous user and implement the logic for button click events.

On Windows, press Ctrl+F12, or, on a Mac, press command+F12, and type offlineTransactionIssueAction to move to the offlineTransactionIssueAction method. When the transaction error occurs, make the Offline Transaction Issue Screen visible, set the information of the previous user and provide your logic for the button click event. To get the information of the previous user, call the getPreviousUser method of the OfflineODataProvider class to get the user ID and then call the getUserInfoByIdAsync method of the UserSecureStoreDelegate class to get the user information.

The Flows component exposes two APIs in the UserSecureStoreDelegate class for you to acquire user information by ID, such as user name and email:

fun getUserInfoByIdAsync(userId: String) : DeviceUser?

fun getUserInfoById(userId: String): DeviceUser?

The getUserInfoByIdAsync function is mainly used by the Java code. Notice that this function can only be called after the onboarding or restore flow.

After onboarding, the setting for multi-user mode enablement is saved in the local database. To get this setting, the UserSecureStoreDelegate class exposes the following API:

suspend fun getRuntimeMultipleUserMode(): Boolean?

fun getRuntimeMultipleUserModeAsync(): Boolean?

The getRuntimeMultipleUserModeAsync function is mainly used by the Java code.

The Flows component exposes two APIs in FlowActionHandler class for you to obfuscate the user name and email displayed on the Sign-in screen:

open fun obfuscateUserName(name: String): String

fun obfuscateEmail(email: String): String

Notice that a default obfuscate algorithm is provided in the APIs. You can override the APIs to provide your own obfuscate algorithm.

The FlowStateListener class provides one callback, onOfflineEncryptionKeyReady(key: String?), for you to handle the encryption key ready event.

As a sample implementation of this callback, you can examine a wizard-generated offline app. In Android Studio, on Windows, press Ctrl+N, or, on a Mac, press command+O, and type WizardFlowStateListener to open WizardFlowStateListener.java.

On Windows, press Ctrl+F12, or, on a Mac, press command+F12, and type onOfflineEncryptionKeyReady to move to the onOfflineEncryptionKeyReady method. Examine the code and notice that it does some clean and reset work:

You can provide your own logic in this callback.