Working with the Unblu Android mobile SDK

The Unblu `View`

All Unblu UI content is rendered in a View that’s available via the UnbluClient.getMainView getter.

The View the getter returns is a container which can contain other view elements as well as a WebView that most of the Unblu UI is rendered in.

The Unblu UI returned by the UnbluClient.getMainView shows all existing conversations or the conversation currently open. These conversations can be used to chat and make calls.

For the view to be visible on the device, you need to add it to a view hierarchy somewhere in your app. The size and position of the Unblu view within the context of your application are up to you. However, since the view has a lot of content, you should try to give it a large amount of space.

Listing 1. Adding the Unblu View to a layout

Unblu.createVisitorClient(this,
        activity,
        unbluConfiguration,
        notificationApi,
        new InitializeSuccessCallback<UnbluVisitorClient>() {
            @Override
            public void onSuccess(@Nullable UnbluVisitorClient instance) {
                Toast.makeText(UnbluDemoApplication.this, "UnbluApi initialized!", Toast.LENGTH_SHORT).show();
                unbluVisitor = instance;

                //Add the view to the desired layout
                layoutContainer.addView(unbluVisitor.getMainView(),
                        new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));

                //...
            }
            @Override
            public void onPreloadSuccess() {
          }
        },
        new InitializeExceptionCallback() {
            @Override
            public void onConfigureNotCalled() {
            }
            @Override
            public void onInErrorState() {
            }
            @Override
            public void onInitFailed(@NonNull UnbluClientErrorType errorType, @Nullable String details) {

            }
        });

You can add a back button to the Unblu UI that enables the user to explicitly hide the Unblu UI. For visitors, set the following configuration properties:

Set com.unblu.visitor.ui.showOverviewActionBarCollapseAction to true.
Set com.unblu.visitor.mobile.ui.overviewActionBarCollapseActionDisplayMode to BACK_BUTTON.

If you set it to COLLAPSE_BUTTON, you should review the configuration property com.unblu.visitor.mobile.ui.allowCollapseButton as well.

For agents the relevant configuration property is com.unblu.agent.mobile.ui.showInboxActionBarCollapseAction.

If there’s an issue with the Unblu SDK, be aware that the UI is rendered inside a WebView, so you can attach the local Chrome to check for error logs. It’s a limitation of Android WebViews that you can’t see the full content of logs in the normal debugger console.

Note that several functions, like opening a conversation and starting an audio/video call, require that the UI opens at least once so that the corresponding part gets loaded by JavaScript. You can find more details in the JS API documentation.

Re-attaching the Unblu `View`

When you enable the modal view, the SDK presents the Unblu View in a separate layer. Dismissing the modal view detaches the Unblu UI from your layout. Whether it gets re-attached automatically depends on the lifecycle of the activity that hosts the Unblu View:

If the hosting activity was destroyed while the modal view was shown, the system recreates it through onCreate when the user returns. Provided you add the Unblu View to your layout in onCreate, as shown above, the UI re-attaches automatically.
If the hosting activity was only paused—for example, because the modal view was displayed on top of it—the system calls onResume when the user returns, not onCreate. In this case the SDK doesn’t re-attach the Unblu View, and the Unblu UI doesn’t reappear.

To cover the second case, re-attach the Unblu View in the onResume method of the activity that hosts it:

Listing 2. Re-attaching the Unblu View in onResume

@Override
protected void onResume() {
    super.onResume();
    if (unbluVisitor == null) {
        return; (1)
    }
    View unbluView = unbluVisitor.getMainView();
    ViewParent parent = unbluView.getParent();
    if (parent instanceof ViewGroup) {
        ((ViewGroup) parent).removeView(unbluView); (2)
    }
    layoutContainer.addView(unbluView,
            new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT)); (3)
}

1	The client isn’t necessarily initialized the first time `onResume` runs. If it isn’t, there’s nothing to re-attach.
2	A `View` can only have one parent, so detach the Unblu `View` from its current parent before re-attaching it.
3	Add the Unblu `View` back to your layout container.

JavaScript availability

JavaScript served in the Unblu view is only ever loaded from the URL endpoint that points to the Unblu Collaboration Server in your app’s configuration. The API that allows JavaScript to call native code consists of clearly defined interfaces, and all inputs are validated by the mobile SDK before execution. Any calls that fall outside the scope of the interfaces, or that fail validation, are rejected by the SDK.

Conversations

The UnbluConversation interface provides the necessary APIs to interact with conversations in Unblu. This includes actions such as closing the conversation, starting audio or video calls, and launching mobile co-apping sessions.

The functions that start calls and mobile co-apping sessions require the presence of the CallModule or MobileCoBrowsingModule, respectively. If the required module isn’t registered in the Unblu client instance, an error is thrown at runtime.

For the collaboration layers you can use once a conversation is running, refer to Mobile collaboration layers.

The current open conversation is always available via the UnbluClient.getOpenConversationValue getter. If no conversation is currently open, the returned value is null.

If you wish to be notified when a conversation is opened or closed, subscribe to the UnbluClient.getOpenConversation observable in your app.

The main functions of note on the UnbluClient relating to conversations are:

Additionally, the UnbluVisitorClient provides:

You can intercept conversation-related activity by calling UnbluVisitorClient.setConversationInterceptor with an object that conforms to the ConversationInterceptor interface.

Private views and areas

Private views and areas are part of mobile co-apping. For how to use them, refer to Mobile collaboration layers.

Named areas

Similar to a web page, the named area feature is also available for the mobile SDKs.

You can set a named area by calling UnbluClientConfiguration.Builder.setNamedArea before you initialize the API. Alternatively, you can set a named area by calling the UnbluVisitorClient.setNamedArea method on the UnbluVisitorClient instance.

If a named area is set before initializing the API, its specific configuration is loaded upon initialization. Setting the named area after initialization, on the other hand, has no effect on the loaded configuration and doesn’t affect existing conversations. It only changes the requests for new conversations in the Agent Desk queue in the way that the agent can filter by the named area.

As a result, it’s important to know if there are any relevant configuration properties set in the named area scope. If there is, the named area must be set in the SDK before initializing the API. If a named area is only used for the queue, it can be set at any time before starting a new conversation.

Custom cookies

You can define custom cookies to send to the Unblu server with each request. This is possible either upon initialization, by calling the UnbluClientConfiguration.Builder.setCustomCookies method, or dynamically by calling the UnbluClient.setCustomCookies method on the client instance.

Before the API is initialized, the last cookies configured are used. If the API is already initialized, cookies with the same name are overridden and new cookies are added.

Cookies defined previously remain until the API is deinitialized. If the API is then initialized again, only the last defined cookies are used again.

Color mode

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

Your app can match the Unblu UI to its own light or dark theme. To set the color scheme of the Unblu UI, call UnbluClient.setColorScheme with one of the UnbluColorScheme constants. LIGHT and DARK force the respective mode. AUTO follows the device’s color setting as it was when the Unblu client was initialized.

Listing 3. Matching the Unblu UI to your app’s theme setting

/* Your app's settings screen calls this when the user picks a theme.
   `AppTheme` is your app's own type. */
fun onAppThemeSelected(appTheme: AppTheme) {

    // Apply the theme to your own UI first.
    // ...

    val colorScheme = when (appTheme) {
        AppTheme.LIGHT -> UnbluColorScheme.LIGHT
        AppTheme.DARK -> UnbluColorScheme.DARK
        AppTheme.SYSTEM -> UnbluColorScheme.AUTO
    }

    /* `unbluClient` is the client returned by
       `Unblu.createVisitorClient` or `Unblu.createAgentClient`. */
    unbluClient?.setColorScheme(colorScheme)
}

Calling setColorScheme on a deinitialized Unblu client throws an IllegalStateException.

When a change takes effect depends on the color scheme evaluation mode. The camera, file previews, and the document collaboration viewer read the color scheme when they open, so a change doesn’t affect them while they’re on screen. Close and reopen them to apply the new color scheme. The call UI always uses fixed dark colors, so the color scheme doesn’t affect it.

Your app can call setColorScheme again at any time to change the color scheme. Once it has set a color scheme, though, the color scheme configured on the Unblu server no longer applies. The server configuration takes effect again only after the client is reinitialized.

If the user changes the color setting on their device while your app is running, the Unblu UI keeps its current color scheme until the client is initialized again. To have the Unblu UI follow the device while your app is running, set LIGHT or DARK explicitly instead of relying on AUTO.

Listing 4. Following the device’s color setting while the app is running

/* Android calls this when the device configuration changes, including the
   color setting. Your activity must declare `android:configChanges="uiMode"`
   for this to happen; otherwise Android recreates the activity instead. */
override fun onConfigurationChanged(newConfig: Configuration) {
    super.onConfigurationChanged(newConfig)

    val nightMode = newConfig.uiMode and Configuration.UI_MODE_NIGHT_MASK
    val colorScheme = if (nightMode == Configuration.UI_MODE_NIGHT_YES) {
        UnbluColorScheme.DARK
    } else {
        UnbluColorScheme.LIGHT
    }

    unbluClient?.setColorScheme(colorScheme)
}

For the server configuration properties and how an app override interacts with them, refer to Color mode in the mobile SDK configuration article.

Uploading files and camera pictures or videos

When the user of the app tries to upload a file in the Unblu chat UI, the file chooser appears. By default, the user may select either an existing file or create a new picture/video with their phone’s camera app.

You can restrict the file types that users may upload with the following configuration properties:

The specific behavior of com.unblu.filemanager.fileTypeInputTagHint varies between device vendors. Android may filter out file types that you don’t want to exclude. You should take this into account when deciding whether to enable the configuration property for Android devices.

In Android, the camera app can’t write a picture directly to the app’s internal storage, so it stores a temporary file in the external storage of the Android system. This can be a security issue, so the SDK allows you to disable the upload of new pictures/videos from the camera app. Use the UnbluClientConfiguration.Builder.setCameraUploadsEnabled method to change the configuration.

It’s also possible to enable or disable photo or video uploads from the user’s camera.

Picture-in-Picture (PiP)

Starting with version 4.9.1, the Unblu Android mobile SDK uses the built-in system Picture-in-Picture (PiP) functionality. This works both within and outside the app.

Configuring behavior when dismissing system PiP

The default behavior when a user drags the system PiP and drops it into the area with the X icon is for Unblu to end the call and the conversation. You can change this behavior with the method UnbluClient.setEndCallOnPipDismiss.

Enabling PiP support

To display PiP content within the app, the SDK uses an internal activity. The same activity is used when the user navigates to the home screen, provided PiP content is already being displayed in the app.

However, if the user navigates to their home screen during a call and the in-app PiP isn’t being displayed because the call is using the entire screen, the PiP outside the app uses the activity hosting the UnbluView. If that activity doesn’t have PiP support enabled (android:supportsPictureInPicture = "true") in your app’s manifest, the PiP won’t be visible to the user.

If the in‑app PiP is already visible, the SDK tries to add the video to the DecorView of the host activity’s window (and removes it when returning from PiP), thus hiding the host UI. If this doesn’t work for your app—because it has a complex UI and you have to hide additional content manually, for example—override Activity#onPictureInPictureUiStateChanged(pipState: PictureInPictureUiState) (if you’re targeting API version 35 or later) or Activity#onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean, newConfig: Configuration) (if you’re targeting API version 34 and earlier).

For more information, refer to Use picture-in-picture (PiP) in the Android developer documentation.

Native PDF previews

The Unblu Android mobile SDK has two ways of displaying previews of PDF files:

If the Android API level is 34 or older, the SDK uses its own embedded preview implementation to display the PDF file.
If the Android API level is 35 or newer, you can use the Google PDF viewer, provided your app has added a dependency to it. At the time of writing the dependency is androidx.pdf:pdf-viewer-fragment:1.0.0-alpha10.

The SDK checks both requirements, the API level and the presence of the dependency. It only uses the Google PDF viewer if both requirements are met, otherwise it reverts to the embedded preview of the PDF file.

Using the Google PDF viewer is the recommended approach. You should only revert to the SDK’s embedded preview implementation if you don’t meet the requirements for the Google PDF viewer.

Document collaboration

For how to use the document collaboration layer in the Android SDK, refer to Mobile collaboration layers.

Visitor data

The term "visitor data" refers to data about a visitor that isn’t directly related to Unblu but may be required by some other system. This could be something like information about where exactly a visitor started the conversation that’s needed by a backend system to decide how to proceed. Conversely, it might be the outcome of some interaction with a backend system that influences the frontend in some way.

You can set visitor data in the Android SDK by passing it in as a parameter of the startNewConversation method on the UnbluVisitorClient instance. Alternatively, call the method setVisitorData.