Enable Multi-User Mode for Your Android Application

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

On Windows, press Ctrl+Shift+N, or on a Mac, press command+Shift+O, and type sap_mobile_services.json to open sap_mobile_services.json.

Change the value of multiUser from false to 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 sap_mobile_services.json. 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 (reset/uninstall first) the app and notice that the onboarding process is same as for single-user mode, except that no biometric authentication screen is shown. After onboarding, put the app in background until the sign in screen appears. In multi-user mode, there is a Switch 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.

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.kt.

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

val flowContext =
            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.

On Windows, press Ctrl+Shift+N, or on a Mac, press command+Shift+O, and type sap_mobile_services.json to open sap_mobile_services.json.

Change the value of multiUser from false to true.

Re-run (reset/uninstall first) the app and notice that the onboarding process is same as for single-user mode, except that no biometric authentication screen is shown. After onboarding, put the app in background until the sign in screen appears. In multi-user mode, there is a Switch 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 Client Settings in the general settings 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 multiUser in sap_mobile_services.json 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.kt.

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

/*
 * Create OfflineODataProvider
 * This is a blocking call, no data will be transferred until open, download, upload
 * @return if initialization needed
 */
suspend fun initializeOffline(
    context: Context,
    appConfig: AppConfig,
    runtimeMultipleUserMode: Boolean
): Boolean {
    ...

    try {
        val url = URL(serviceUrl + CONNECTION_ID_ESPMCONTAINER)
        val offlineODataParameters = OfflineODataParameters().apply {
            ...

            isForceUploadOnUserSwitch = runtimeMultipleUserMode
            val encryptionKey = if (runtimeMultipleUserMode) {
                UserSecureStoreDelegate.getInstance().getOfflineEncryptionKey()
            } else { //If is single user mode, create and save a key into user secure store for accessing offline DB
                ...
            }
            storeEncryptionKey = encryptionKey
        }.also {
            ...
        }
        logger.debug("start init offline odata provider")

        ...

        return true
    } catch (e: Exception) {
        logger.error("Exception encountered setting up offline store: " + e.message)
        throw e
    }
}

In OfflineOpenViewModel.kt:

init {
    viewModelScope.launch(Dispatchers.Default) {
        val isMultipleUserMode =
            UserSecureStoreDelegate.getInstance().getRuntimeMultipleUserMode()
        val appConfig = FlowContextRegistry.flowContext.appConfig

        if (OfflineWorkerUtil.initializeOffline(application, appConfig, isMultipleUserMode)) {
            startOpenOffline()
        } else {
            _uiState.update { currentState ->
                currentState.copy(
                    result = OpenResult.OpenSuccess()
                )
            }
        }
    }
}

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 (reset/uninstall first) the app. Notice that the onboarding process and add/switch user process are the same as for the online app.

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 Client Settings in the general settings 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.

Enable multiUser in sap_mobile_service.json 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.kt.

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

/*
 * Create OfflineODataProvider
 * This is a blocking call, no data will be transferred until open, download, upload
 */
@JvmStatic
fun initializeOffline(
    context: Context,
    appConfig: AppConfig,
    runtimeMultipleUserMode: Boolean
) {
    ...

    try {
        ...

        val offlineODataParameters = OfflineODataParameters().apply {
            ...

            isForceUploadOnUserSwitch = runtimeMultipleUserMode
            val encryptionKey = if (runtimeMultipleUserMode) {
                UserSecureStoreDelegate.getInstance().getOfflineEncryptionKey()
            } else { //If is single user mode, create and save a key into user secure store for accessing offline DB
                ...
            }
            storeEncryptionKey = encryptionKey
        }.also {
            ...
        }

        ...
    } catch (e: Exception) {
        logger.error("Exception encountered setting up offline store: " + e.message)
    }
}

In MainBusinessActivity.kt:

override fun onResume() {
    super.onResume()

    ...

    spforLockAndWipe.getString(SAPWizardApplication.LOCK_WIPE_INVOKING_FLAG, null)?.let {
        spforLockAndWipe.edit().remove(SAPWizardApplication.LOCK_WIPE_INVOKING_FLAG).apply()
    } ?: run {
        ...

        val isMultipleUserMode = UserSecureStoreDelegate.getInstance().getRuntimeMultipleUserModeAsync() == true

        ...

        OfflineWorkerUtil.initializeOffline(application, appConfig, isMultipleUserMode)

        ...
    }
}

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 (reset/uninstall 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.

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

On Windows, press Ctrl+Shift+N, or on a Mac, press command+shift+O, and type OfflineSyncScreen to open OfflineSyncScreen.kt.

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

OfflineNetworkIssueScreen(
    onBackButtonClick = navigateToWelcome,
    onMainButtonClick = viewModel::startOpenOffline
)

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+F, or on a Mac, press command+F, and type SyncFailureType.TRANSACTION_ISSUE to move to the transaction issue handling. When the transaction issue 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 OfflineOpenViewModel class.

viewModel.previousUser?.let {
                OfflineTransactionIssueScreen(
                    userName = it.name,
                    email = it.email,
                    onBackButtonClick = navigateToWelcome,
                    onMainButtonClick = navigateToWelcome
                )
            } ?: throw IllegalStateException("Unexpected offline transaction issue without previous user")

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.kt.

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.

private fun offlineNetworkErrorAction() {
    this@MainBusinessActivity.runOnUiThread {
        binding.offlineNetworkErrorScreen.visibility = View.VISIBLE
        binding.offlineInitSyncScreen.visibility = View.INVISIBLE
        binding.mainBusResumeProgressBar.visibility = View.INVISIBLE
        val offlineNetworkErrorScreenSettings = OfflineNetworkErrorScreenSettings.Builder().build()
        with(binding.offlineNetworkErrorScreen) {
            initialize(offlineNetworkErrorScreenSettings)
            // Provide logic for the button click event
            setButtonClickListener(View.OnClickListener {
                OfflineWorkerUtil.addProgressListener(progressListener)
                OfflineWorkerUtil.open(application)
                startEntitySetListActivity()
                supportActionBar?.setTitle(R.string.initializing_offline_store)
                binding.offlineNetworkErrorScreen.visibility = View.INVISIBLE
                binding.offlineInitSyncScreen.visibility = View.VISIBLE
            })
        }
    }
}

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 getPreviousUserDetails method from the flow context.

private fun offlineTransactionIssueAction() {
    this@MainBusinessActivity.runOnUiThread {
        binding.offlineTransactionIssueScreen.visibility = View.VISIBLE
        binding.offlineInitSyncScreen.visibility = View.INVISIBLE
        binding.mainBusResumeProgressBar.visibility = View.INVISIBLE
        val offlineTransactionIssueScreenSettings = OfflineTransactionIssueScreenSettings.Builder().build()
        with(binding.offlineTransactionIssueScreen) {
            initialize(offlineTransactionIssueScreenSettings)
            CoroutineScope(IO).launch {
                val user = FlowContextRegistry.flowContext.getPreviousUserDetails()
                withContext(Main) {
                    user?.let {
                        setPrevUserName(it.name)
                        setPrevUserMail(it.email)
                    } ?: run {
                        setPrevUserName(OfflineWorkerUtil.offlineODataProvider!!.previousUser)
                    }
                }
            }
        }
        binding.offlineTransactionIssueScreen.setButtonClickListener(View.OnClickListener {
            startActivity(Intent(this, WelcomeActivity::class.java).apply {
                addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
            })
        })
    }
}

The Flows-Compose component exposes one API in the UserSecureStoreDelegate class for you to acquire user information by ID, such as user name and email:

suspend fun getUserInfoById(userId: String): DeviceUser?

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

The Flows component expose the following API in FlowContext class for you to acquire the details of the previous user, such as user name and email:

fun getPreviousUser() : DeviceUser?

The Flows component exposes one API in FlowActionHandler class for you to customize the user information displayed on the Sign-in and user list screens, that will obfuscate the user name and email by default:

open fun customizeSignInScreenUserInfo(user: DeviceUser): SignInScreenUserInfo

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.

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?

suspend 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 expose the following API in FlowContext class for you to acquire the details of the previous user, such as user name and email:

fun getPreviousUserDetails() : DeviceUser?

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

open 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.kt.

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

override fun onOfflineEncryptionKeyReady(key: String?) {
    logger.info("offline key ready.")
    userSwitchFlag =  if (!application.preferenceManager.getBoolean(OfflineWorkerUtil.PREF_DELETE_REGISTRATION, false)) {
        flowContext.getPreviousUserId()?.let {
            flowContext.getCurrentUserId() != it
        } ?: false
    } else {
        application.preferenceManager.edit().putBoolean(OfflineWorkerUtil.PREF_DELETE_REGISTRATION, false).apply();
        OfflineWorkerUtil.resetOffline(application)
        true
    }

    OfflineWorkerUtil.userSwitchFlag = userSwitchFlag

    /*
     * In single user scenario,
     * if offline data store initialized and its encryption key not found,
     * close and remove offline data store, meanwhile, set userSwitchFlag to true to trigger some important setting
     */
    if (UserSecureStoreDelegate.getInstance().getRuntimeMultipleUserModeAsync() == false
            && application.preferenceManager.getBoolean(OfflineWorkerUtil.PREF_OFFLINE_INITIALIZED, false)
            && UserSecureStoreDelegate.getInstance().getData<String>(OfflineWorkerUtil.OFFLINE_DATASTORE_ENCRYPTION_KEY) == null) {
            userSwitchFlag = true
            OfflineWorkerUtil.resetOffline(application)
    }

    if (userSwitchFlag) {
        application.preferenceManager.apply {
            edit().putBoolean(OfflineWorkerUtil.PREF_OFFLINE_INITIALIZED, false)
                    .apply()
        }
        application.repositoryFactory.reset()
        OfflineWorkerUtil.offlineODataProvider?.close()
        OfflineWorkerUtil.resetOfflineODataProvider()
    }
}

You can provide your own logic in this callback.