SDK Interface

SDK Status

The general status of the SDK can be observed from the getStatus() method.
Possible values and their expected values are:

  • NotLoggedIn: Initial state of the SDK
  • Initializing: Either user was previously logged-in and the SDK is recovering the saved information on a background thread; or a login command was just executed and it’s being processed. On both cases the status should update shortly.
  • Ready: The Login/Initialization completed successfully and the functions of the SDK can be used.
  • LoggingOut: A logout execution have been triggered and it’s being processed

Additionally NotLoggedIn and LoggingOut contains a user-friendly message string and a Reason enum.
When a LoggingOut occurs, the message and reason will be copied over to the following NotLoggedIn status.
The Reason values are:

  • NotLoggedIn: Initial state as soon as the SDK is instantiated.
  • UserNotAuthorised: The user is not authorized with the Smart Workspaces backend. This might happen due to a login failed (wrong username/password/token) or due to a revoked authorization on the backend side (HTTP-401403).
  • EncryptionFailure: There was a problem initializing the SDK due to an encryption issue. The data is cleared during LoggingOut and a new call to login() should pass without issues on the next attempt.
  • ClientApplicationRequestedLogout: The client app called the logout() method.

Login

The SDK provides 3 different types of login for the user

  • Username and Password
  • OAuth2
  • external Token Login

Login via username and password

val result : LiveData<SimpleResponse<Void>> = sdk.usernamePasswordLogin(username, password)
result.observe(this)
      .onSuccess {
        // login success
      }
      .onFail { exception ->
        // login fail
      }
Java

Login via OAuth2

To login with OAuth2 you have to do the login in an external Webview and add a deep-link back into the app.
The deep-link URI have to be configured on the backend.
The URL to call for the external url consists of the BASE_URL + /auth/ + OAUTH_ID

Kotlin

val uri = Uri.parse("${baseUrl}/auth/${oauthId}")
CustomTabsIntent.Builder()
    .build()
    .launchUrl(activity, uri)

Java

We recommend the use CustomTabsIntent class of Android. All security conscious oauth2 providers blocks the usage of built-in WebView. To use the CustomTabsIntent you have to add implementation "com.android.support:customtabs:<latest>" as a dependency into your build.gradle file

After the login succeeded the WebView will deep-link back into your application which will receive the redirectedUrl on the Intent to login to the SDK.

Kotlin
val result : LiveData<SimpleResponse<Void>>  = sdk.oAuth2Login(intent.dataString)
Java

The result of the login operation can be observed similarly to the username and password login

Login using external Token

To login the user using server-to-server pre-shared authentication token your backend has to register a token for the user on the Smart Workspace Server and provide it to the following method.

Kotlin
val result : LiveData<SimpleResponse<Void>> = sdk.externalTokenLogin(authToken)
Java

The result of the login operation can be observed similarly to the username and password login

Login failed

If the login failed the state of the SDK will be SmartWorkspaceSdk.Status.NotAuthorized and then SmartWorkspaceSdk.Status.NotLoggedIn for all login variations. SmartWorkspaceSdk.Status.NotAuthorized also has a message string with the explanation, why the authorization failed.

Logout

To logout a user simply call the logout() method:

sdk.logout()
Java

This method doesn’t return a LiveData<Response> because its result can be directly observed on the SDK status

Change Password

You can only change the password, if you are using login via username and password

You can change the password of a logged in user, like in the following example:

val result : LiveData<SimpleResponse<Void>> = sdk.changePassword(oldPassword, newPassword, newPasswordConfirm)
result.observe(this)
      .onSuccess {
        // change password success
      }
      .onFail { exception ->
        // change password fail
      }
Java

User

To get all available user information (f.e. email, firstname, lastname, salutation) use the following code

Kotlin
val user : LiveData<User> = sdk.getUser().onSuccess()
user.observe(this, Observer { user ->
    user?.let {
        
    }
})
Java

Refresh

There’s also a refresh method() that will re-query backend for latest information regarding user, units, schedules, etc. Existing LiveData<Response> will change their state to executing