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) {

            }
        });

If there is an issue with the Unblu SDK, please 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.

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 any 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-browsing sessions.

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

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

The SDKs provide a simple way to add specific views which shouldn’t be shown on the remote side. To do this, the MobileCoBrowsingModule provides the function addPrivateView which takes an ID as its argument. Each view has its own ID.

After a view ID is added, it’s automatically overlaid by an image before the screen is transmitted to the remote side. You can make a view visible to the remote side again by calling the removePrivateView function.

The SDK also provides a way to specify areas which shouldn’t appear on the remote side. The MobileCoBrowsingModule includes the setPrivateArea method which takes a custom ID, values for the x and y axes, and values for the width and height of the private area. Each private area has its own ID. This is especially useful if your app is a hybrid app, or is built with some cross-platform framework that doesn’t have views with IDs.

Once an area is added, it’s automatically overlaid by an image before the screen is transmitted to the remote side. To make an area visible to the remote side again, call the function removePrivateArea.

Animations and private views and areas

If you use animations to transition from a view that contains a private view or area, the overlay may not conceal the content during the entire transition.

If you know your app uses animations in views that contain private views or areas, you should take measures to ensure that the content isn’t exposed during the animation. For example, if you know the animation is always horizontal, you might make the overlay larger, so that it covers the area the concealed content traverses during the animation.

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.

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.