Blocking Users¶
To block the user from sending requests to the server, the administrator can either:
For versions prior to SAP BTP SDK for Android version 7.1, follow this guideline to handle blocking/locking/wiping. As of SAP BTP SDK for Android version 7.1, the LockAndWipeService is introduced to simplify this process.
LockAndWipeService¶
Signature¶
LockAndWipeService handles the lock and wipe cases that are either triggered by the policy settings or manually executed by the administrator. The signature and the main functions are as follows:
class LockAndWipeService(private val onBlockedByServer: suspend ((ServerBlockType) -> Unit) = {}) :
MobileService(), InterceptorProvider {
fun setCurrentUser(currentUserId: String?) { ... }
fun checkWipeAndLockStatus(): LockWipeActionType? { ... }
}
enum class LockWipeActionType {
LOCK, WIPE
}
Initialize the Service¶
To enable this feature in your app, create an instance of LockAndWipeServer and initialize it using SDKInitializer. For example:
SDKInitializer.start(application, LockAndWipeService())
Current User and Policy¶
LockAndWipeService listens to the client policy changes internally to update the policy of the current user. Make sure that setCurrentUser is called first before sending out policy change events using:
SDKInitializer.notifyClientPoliciesRetrieved(clientPolicies)
Server Block Callback¶
LockAndWipeService is an InterceptorProvider, which means that if you're using the Flows component of SAP BTP SDK for Android for onboarding, the okHttpClient saved in ClientProvider will automatically have an interceptor added to update the last successful connection time and notify the service when the administrator blocks or wipes the user registration using onBlockedByServer. The client code can identify the server block types using the ServerBlockType parameter.
enum class ServerBlockType {
TRAFFIC_REG_BLOCKED,
REG_BLOCKED,
TRAFFIC_BLOCKED,
TRAFFIC_REG_WIPED,
TRAFFIC_REG_LOCKED
}
Note
onBlockedByServer will be called in the Main coroutine scope, please make sure your logic here does not interrupt the current user process.
Lock/Wipe Status¶
The function ofcheckWipeAndLockStatus is to check the current the lock or wipe status determined by the client policies. The client code can call this function when needed, then decide what to do according to the return status.
Integration in the Flows Component¶
If you're using the Jetpack Compose based Flows component of SAP BTP SDK for Android for onboarding, the restore flow will do the above things for you to simplify the integration if LockAndWipeService is initialized with SDKInitializer.
Integration Cases¶
- The restore/timeout flow will check the lock/wipe status after passcode is provided.
- If the user registration should be wiped by checking the wipe policy, the restore flow will delete the user registration then cancel the restore/timeout flow.
- If the user registration should be locked by checking the lock policy, the restore flow will logout the user first then ask the user to re-authenticate to unlock the registration. If the authentication succeeds, the restore flow will continue, otherwise, it will be canceled after showing an error dialog with the reason.
- The restore flow has several requests to server, for example, retrieving the client policy, or download the custom theme file, if the response indicates the user registration is blocked or wiped by the administrator, the flow will be canceled after logging out the user or deleting the registration.
Changes in the Flows Component¶
The Flows component implements several changes in order to integrate the LockAndWipeService.
FlowOptions¶
A new property, handleLockAndWipeInRestoreFlow, is added in FlowOptions to support the client code being able to decide whether to let the restore flow handle the lock/wipe cases. The default value of this property is 'true'. If you want to use LockAndWipeService to update the last successful connection time of users and handle the locking/blocking/wiping by yourself, you can set this option to 'false'.
val handleLockAndWipeInRestoreFlow: Boolean = true
Restore Flow Cancellation¶
If LockAndWipeService is not initialized in SDKInitializer, unless the user clicks the Reset button on the sign-in screen, the client code will not be notified that the restore/timeout flow has been canceled. The new behavior is that the restore/timeout flow will be canceled if the registration is locked, blocked, or wiped. The client code can use the following code to handle such cases:
FlowUtil.startFlow(
context,
flowContext = DemoApplication.getOnboardingFlowContext(context),
) { resultCode, data ->
if (resultCode == Activity.RESULT_OK) {
val intent = Intent().apply {
setClass(context, MainActivity::class.java)
addFlags(
Intent.FLAG_ACTIVITY_NEW_TASK or
Intent.FLAG_ACTIVITY_CLEAR_TASK or
Intent.FLAG_ACTIVITY_CLEAR_TOP
)
}
startActivity(intent)
finish()
} else {
//canceled
data.getFinishedFlowName()?.also { flowName ->
//flowName could be the name of FlowType.Reset, FlowType.Logout or FlowType.DeleteRegistration
...
}
startOnboarding(context)
}
}
For the 'timeout' flow, because the callback is not provided by the client code, the SDK has to use a different method to notify the client code. In the onFlowFinished callback of your FlowStateListener, you can do the following to handle the cancellations:
override suspend fun onFlowFinished(flowName: String?) {
logger.debug("Finished flow name: $flowName")
when (flowName) {
FlowType.Reset.name,
FlowType.Logout.name,
FlowType.DeleteRegistration.name -> {
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.onFlowFinished(flowName)
}
}
onBlockedByServer of LockAndWipeService¶
The onBlockedByServer callback of LockAndWipeService will NOT be called when the onboarding or restore flow is running, in order to prevent duplicate logic from being executed. After the flows, if an API call in the client code captures the block or wipe error responses, the callback will be notified.