Android mobile SDK integration

Requirements

The Android mobile SDK requires Android version 7 or newer.

Before you start, make sure that you are using the D8 dex compiler and JDK 11 or newer to build your app.

Resource requirements when in use

The Android mobile SDK is approximately 3 MB large, although the space required after installation is greater and varies with the dependencies required for your use case.

When running, the Android mobile SDK uses around 25 MB of RAM. Initializing the SDK uses an additional 3—4 MB of RAM. Due to the variety of CPUs used in Android mobile devices, it’s difficult to state how much the SDK affects CPU usage. As a rough guide, using messaging may cause spikes of up to 10% CPU usage, whereas audio or video calls may result in CPU usage of around 50%, and RAM usage can increase up to 400 MB.

Network traffic

During initialization, the SDK downloads approximately 0.3 MB of JavaScript files. The UI requires downloading around 2.5 MB of additional resources. Some of these downloads may be cached on the device, resulting in less network traffic for later uses.

For text messaging, only the message itself and the HTTP request overhead is transmitted.

By default, Unblu transmits an image around 5 times per second in mobile co-browsing sessions if the content has changed. You can adjust the maximum frame capture rate with the configuration property com.unblu.mobiledevice.androidMaxFpsRate. The size of the image depends on the size of the mobile device’s screen but is typically 5—20 KB large.

In audio and video calls, network traffic depends on the quality of the connection, as both Vonage and LiveKit change the codec based on the network connection.

Android archive integration

For Android, Unblu provides android archive (AAR) files with additional source JARs for public classes and Javadoc JARs for them. Those files are delivered within a .tar.gz file for the SDK. The TAR files have the internal structure of a maven repository.

Unblu is divided into modules, and depending on your implementation, you may use all, or only some of them.

To integrate the SDK, the TAR files have to be extracted into the project folder of the app. To add it to the project, the following lines need to be added to the app/build.gradle file:

repositories {
    ...
    mavenCentral() (1)
    maven {
        url "../unblu-mobile-sdk"
    }
}
...
dependencies {
    ...
    implementation 'com.unblu.mobile-sdk-android:coresdk:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:firebasenotificationmodule:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:callmodule:4.0.0'
    implementation 'com.unblu.mobile-sdk-android:mobilecobrowsingmodule:4.0.0'
}

1	This line is required if you use the Unblu audio and video call feature in your app. The Unblu call module has a dependency on the Vonage (formerly OpenTok) Android SDK provided by the Vonage Video API.

This way all dependencies of the SDK are automatically retrieved.

The *-public-sources.jar files only contain the sources for the public API part and cannot be used as a library as they don’t contain the internal classes.

The Unblu SDK’s firebasenotificationmodule uses Firebase Cloud Messaging for push notifications. For Firebase to work correctly, the google-services.json file from the Firebase project must be added to the app. Additionally, you need to add the following line at the end of your app’s gradle file.

apply plugin: 'com.google.gms.google-services'

Review the instructions for adding Firebase to your app for detailed information.

It is not necessary to set up Firebase in your code. This is done automatically by the SDK when push notifications are enabled.

Permissions

Various features require that you include certain permissions in your application’s manifest.

android.permission.INTERNET: Required to use the internet connection.
android.permission.WRITE_EXTERNAL_STORAGE: Required to save files which should be downloaded.
android.permission.RECORD_AUDIO: Required by Vonage for audio and video sessions (also for plain audio sessions).
android.permission.CAMERA: Required by Vonage for audio and video sessions.
android.permission.WAKE_LOCK: Required to keep the device on during audio and video calls as well as mobile co-browsing sessions.
android.permission.MODIFY_AUDIO_SETTINGS: Required by Vonage for audio and video sessions (also for plain audio sessions).
android.permission.BLUETOOTH: Required by Vonage if bluetooth device is used inside calls.
android.permission.BROADCAST_STICKY: Required by Vonage (no details available).
android.permission.READ_PHONE_STATE: Required by Vonage so the SDK can react appropriately to incoming and outgoing calls.
android.permission.POST_NOTIFICATIONS: Required by Android 13 or higher to send non-exempt notifications, including those from Foreground Services (FGS). Unblu sends such notifications for audio and video calls, for example.

If a user permanently denies access to the camera, microphone, or speakers when the SDK requests it, the SDK won’t display a popup requesting permission anymore. To overcome this, the user must change the settings of their device, either reverting the access denial or granting access directly.

Code setup and initialization

UnbluApplication

To ensure the SDK works properly, you must set the attribute android:name in the application tag of the AndroidManifest.xml file to com.unblu.sdk.core.application.UnbluApplication:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.unblu.testapp">

    <application
        android:name="com.unblu.sdk.core.application.UnbluApplication"> (1)
        </application>
</manifest>

1	There may also be some other attributes

If you implemented your own custom application class that inherits from one of the above classes, set the attribute to that instead.

If you use the Unblu call module and are concerned about the size of the APK file, you should add the attribute android:extractNativeLibs to the application tag and set it to true.

If this isn’t possible in your application, you can use the UnbluApplicationHelper. They define a couple of static functions like onCreate which need to be called in the corresponding functions of the used Application class.

The names of the functions in the helper class are the same as those in the Application class. The documentation also states whether the function must be called before or after the super call.

Unblu client instance

The most important instances of the SDK are UnbluVisitorClient and UnbluAgentClient. Choose the one that suits your implementation.

Instances of both clients can be obtained from the Unblu class:

To create an UnbluVisitorClient instance, call Unblu.createVisitorClient()

If you have an instance of Android.app.Activity already running, please use the alternative Unblu.createVisitorClient() method.
To create an UnbluAgentClient instance, call Unblu.createAgentClient().

If you already have an instance of Android.app.Activity running, use the alternative Unblu.createAgentClient() method.

After the success callback is triggered, the UnbluVisitorClient or UnbluAgentClient instance is provided, and you can obtain the Unblu View, add it to a view tree hierarchy, and display it, start new conversations, check agent availability etc.

You can only have one initialized client instance running throughout your application lifecycle. An instance can either be created directly or only on demand. For example when mobile co-browsing is needed.

Note that if the instance is created on demand, the SDK will take some time until it’s ready and a session can be started. You should also use the method that requires an Android.app.Activity to be passed. Check out the Android mobile SDK reference for an example.

Additionally if you use push notifications, you must initialize an instance at least once. Without it, the Unblu server can’t establish a relationship between a user and their device. We therefore recommend that, in general, you create a client instance as soon as possible, i.e. directly after login.

Unblu client configuration

When you create an instance of either UnbluVisitorClient/UnbluAgentClient, you must provide a configuration for it. Each instance creator accepts an instance of UnbluClientConfiguration. This class will be instantiated with the base URL of the Unblu server and the API key of the Unblu account.

For all possible configurations and their effects, take a look at the documentation of UnbluClientConfiguration.Builder.

Only a limited number of settings can be configured via the Unblu SDKs. All configurations which are independent of the client (the app) can be done via the Unblu Agent Desk.

To properly separate the configurations for the mobile visitor and agent SDKs, as well as configurations of the webpage Unblu is integrated in, we recommend using different API keys for each environment. The Unblu client instance only stores a copy of the configuration. As a result, the client configuration can’t be changed via the reference. If you want to change the client’s configuration, you must destroy the current client instance and create a new one.

The configuration can only be used when creating new instances of UnbluVisitorClient and UnbluAgentClient.

Authentication

If you need to pass authentication information to the Unblu Android mobile SDK, you can either call UnbluClientConfiguration.Builder#setAccessToken() or set custom cookies.

Authorization

If the user is authenticated against an external OAuth 2.0 authentication server that provides the application with an authorization token, the use of the token to authorize a user has two stages:

Assign a token with UnbluClientConfiguration.Builder#setOAuthToken(). You must pass the token before calling Unblu.createAgentClient() or Unblu.createVisitorClient().
Periodically refresh the token with the method `UnbluClient.setAccessToken(). This provides the application with a new access token so the user can continue to work with the application without being prompted.

If the token is invalid, Unblu.onError() emits an ErrorData with UnbluClientErrorType#AUTHORIZATION. In this case, stop the API, assign a valid token, and restart the API.

How to implement the OAuth 2.0 protocol in your Android application—the details of getting a token, refreshing the token, selecting a refresh interval and so on—is beyond the scope of this article. Refer instead to the Android documentation, for example Authenticate to OAuth2 services.

Events

The Unblu Android mobile SDK relies on the RxJava library to handle events and manage data. Before you initialize the API you should subscribe to events in order to be sure not to miss any.

This can be done by calling the Unblu class, which will provide a number of observables you can subscribe to.

Additionally, you can obtain events related to the UnbluClient instance and subscribe to them by calling the instance itself.

Detailed information on the observable events can be found in the documentation of the Unblu/UnbluClient and UnbluVisitorClient classes.

Deinitialization

UnbluVisitorClient and UnbluAgentClient instances can be deinitialized.

If the SDK is no longer needed and everything should get cleaned up, there is the deinitClient function.

The callback parameters can be used to get information about success and errors.

Additionally the Unblu.onError observable can be used as described in the events section above. We strongly recommend that you subscribe to this observable, as errors can occur independently of any explicit calls to the API.

Unblu View

All Unblu UI content is rendered into a View. This view is available via the UnbluClient.getMainView getter. The View it returns provides an Unblu UI that 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. It’s up to you to decide on the view’s size and position within the context of your application.

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 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 opening and 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

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

Private areas

The SDKs provide a way to specify areas which shouldn’t appear on the remote side. To this end, the MobileCoBrowsingModule provides the function setPrivateArea 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.

After an area is added, it is 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.

Custom cookies

It is possible to define custom cookies that should be sent to the Unblu server with each request. This can either be done (initially) by using the function UnbluClientConfiguration.Builder#setCustomCookies, or by setting the cookies dynamically with the setCustomCookies function. Before the API is initialized, always the last cookies configured are used. If the API is already initialized, cookies with the same name are overridden and new cookies are added. The previously-defined cookies will stay until the API is deinitialized. If the API is then initialized again, only the last defined cookies are used again.

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, it can be set by calling UnbluVisitorClient#setNamedArea on the UnbluVisitorClient instance.

If a named area is set before initializing the API, its specific configuration is loaded upon initialization. If it is set later, 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. The named area has no effect for existing conversations.

As a result, it’s important to know if there will be specific configuration on the named area scope. If there is, the named area must be set in the SDK before initializing the API. Bear in mind that you must then change the configuration in API key scope. If a named area is only used for the queue, it can be set at any time before starting a new conversation.

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:

Unfortunately, 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 UnbluClientConfiguration.Builder#setCameraUploadsEnabled(..) to change the configuration.

You can also disable only photo or video uploads individually using link:{android-sdk}com/unblu/sdk/core/configuration/UnbluClientConfiguration.Builder.html#setPhotoUploadsEnabled-boolean-[`UnbluClientConfiguration.Builder#setPhotoUploadsEnabled(..)`] or link:{android-sdk}com/unblu/sdk/core/configuration/UnbluClientConfiguration.Builder.html#setVideoUploadsEnabled-boolean-[`UnbluClientConfiguration.Builder#setVideoUploadsEnabled(..)`], respectively.

Push notifications

If the SDK is configured to use push notifications, there are currently three possible types of notifications visible for the user: Whenever there is a new message, if there is an incoming call, or if there was a missed call. For all types of notification, the system default sounds for notifications and calls should be used to ensure the best user experience. The SDK accomplishes this by using three different notification channels which use the default system sounds.

However, this is only possible—indeed, required—for Android 8.0 Oreo or newer. Before Android 8.0 Oreo, you had to define custom sounds. The name of the sound files must be configured on the Unblu server via the configuration properties com.unblu.mobile.push_notification.androidNewMessageSound and com.unblu.mobile.push_notification.androidIncomingCallSound. We recommend only changing the incoming call sound. The value has to be the name of the file without the file type ending. Within the app, the file must be located at res/raw/<file>.

By default, the icon of the push notifications matches the app icon. Only the parts of the image with an alpha value are displayed. This can lead to a completely gray icon if the app icon has no transparent area. To change the icon to a different image, you can specify a meta-data area inside the app manifest, as in this example:

<meta-data
    android:name="com.google.firebase.messaging.default_notification_icon"
    android:resource="@drawable/ic_notification" />

See the Firebase configuration documentation for further details.

If you wish to use Firebase Push Notifications, you must add the firebasenotificationmodule dependency to your project and get your UnbluNotificationApi from the UnbluFirebaseNotificationService class. See getNotificationApi for further details.

Push notifications sent via Firebase Push Notifications are encrypted by the Collaboration Server, only the notification recipient holds the decryption key.

If push notifications are disabled, the user’s device token is deleted from the Collaboration Server to ensure they don’t receive any push notifications.

Note that the mobile SDK doesn’t provide user a way to manage their devices. This must be done outside the SDK.

Logging

The Unblu SDK uses an internal Logger, which can be configured. Per default the logger does not print any additional and potentially security related information. To change this behavior for debugging purposes, set the flag Unblu#enableDebugOutput to true. Even though the default value of the log level is VERBOSE, in release builds, the verbose and debug logs are removed via proguard rules. You can change the log level by means of the function Unblu#setLogLevel.

It is also possible to enable the flag Unblu#enableCapturingPerformanceLogging to get logs about mobile co-browsing performance. For this the log level has to be DEBUG or less and also the enableDebugOutput flag has to be enabled.

If, for security reasons, you want to strip out the complete log statements from the compiled app, please review the section on log stripping first.

Error handling

Errors can occur while initializing the SDK and at runtime. In both cases,

Initialization errors

Initialization errors are returned via the InitializeExceptionCallback callback passed to the initialization method (see Code setup and initialization above).

If an error occurs during initialization, the user won’t be able to use Unblu. You should either inform user that Unblu is momentarily unavailable or ensure that the Unblu integration isn’t displayed in your app to prevent users from accessing the Unblu UI.

Runtime errors

How you should handle runtime errors depends on the specific error type. The error types are defined in the package com.unblu.sdk.core.errortype.

Most error types are returned on the callback of the method call they’re associated with. For example, if an error occurs when you try to start a mobile co-browsing session by calling UnbluConversation.startMobileCoBrowsing, the MobileCoBrowsingExceptionCallback contains a MobileCoBrowsingErrorType.

Runtime errors can also be emitted via the Unblu.onError() event. The event returns an ErrorData that contains an UnbluClientErrorType.

Most runtime errors aren’t fatal, but the following errors require you to deinitialize and reinitialize the SDK:

Security-relevant configuration

There are several security-related configuration possibilities when integrating the Android mobile SDK. The following points should be taken into consideration to ensure the SDK is configured in the most secure way without limiting the features available.

Whitelist URLs

By default, only the configured Unblu base URL and its subroutes can be accessed by the SDK’s internal WebView. Sometimes you may need to grant the WebView access to other URLs. Examples of situations where this need may arise include:

Redirecting to a different domain
Accessing external resources such as fonts

If your application needs access to other URLs, you can provide a list of regular expressions matching those URLs via UnbluClientConfiguration.Builder#setInternalUrlPatternWhitelist. Otherwise there is no need to configure the internal pattern whitelist as it is secure by default.

The URLs in the internal pattern whitelist are those used internally by your Unblu-enabled application. If you want to specify which URL patterns may be accessed by having your application open another application, modify the external link pattern whitelist described in the following section.

Any URL called, including iframes, is checked against the whitelist before the request is sent to the Collaboration Server.

If you want to use Google fonts in your mobile app, take into account that https://fonts.googleapis.com redirects to https://fonts.gstatics.com. You will have to include a pattern for the latter domain in the whitelist.

External link handler

The Unblu chat UI recognizes different types of links:

URLs such as https://<domain>
mailto:<email_address>
tel:<phone_number>

These links can be clicked by agents or visitors. Doing so opens another application, such as a browser or an email client.

To create an UnbluClientConfiguration, you need to provide an implementation of UnbluExternalLinkHandler. There is a default implementation availabe, which allows two constructors UnbluPatternMatchingExternalLinkHandler, that allows only a small set of link patterns, and UnbluPatternMatchingExternalLinkHandler(List<java.util.regex.Pattern> patternList), which allows you to pass in a customized list of patterns. For example, you may wish to restrict links to those within your organization’s domains.

Certificate pinning

From Android 7.0 Nougat (API 24) on, it is possible to use certificate pinning within your app’s network security configuration file. This may be done for the whole app including all WebViews, so there is no need for the SDK part to provide any configuration for it. Further information on certificate pinning in Android is available in the official documentation.

Download handler

During a conversation, agents and visitors may exchange files. These files can be downloaded and have to be stored somewhere on the user’s device. By default, files are store in the device’s external storage. However, you may prefer to ensure that files are only accessible from within your app for security reasons, and that the app manage downloaded files itself.

To manage downloaded files within your app, you must provide the SDK with a custom implementation of the UnbluDownloadHandler interface via UnbluClientConfiguration.Builder#UnbluDownloadHandler. Any downloads initiated by the user will trigger the custom download handler, which must handle the download itself and store the file somewhere within your app.

Log stripping

The logging section above describes how to configure the log level and whether any values are logged within a log statement.

If you prefer, you can remove log statements from the binary entirely by adapting the app’s proguard-rules.pro file. The SDK already defines the following rules to strip out debug and verbose level debug logs:

-assumenosideeffects class com.unblu.sdk.core.internal.utils.Logger {
    public static *** d(...);
    public static *** v(...);
}

You can do the same for all other log levels, too:

INFO: public static * i(…);
WARN: public static * w(…);
ERROR: public static * e(…);

Data storage

The Unblu View has access to the contents of the data/data/<com.package.name/app_webview directory. However, the mobile SDK doesn’t store any sensitive data in this location, and neither should your app. If you need the mobile SDK to store sensitive data, your app must provide a custom store.

Encrypting stored preferences

The SDK needs to store some internal values inside the app to properly identify the user device against the Collaboration Server even after restarting the app. By default, shared preferences in private mode are used to store those values.

In many cases this is secure enough because normally, only the app itself has access to this data. Sometimes, though, you may wish to encrypt the values before storing them. To do so, provide the SDK with a custom implementation of UnbluPreferencesStorage interface via UnbluClientConfiguration.Builder#setPreferencesStorage. The SDK will use this storage whenever it needs to write or read the value of a preference to persistent storage.

Incoming call notifications

The SDK’s call module displays a notification whenever there’s an incoming call, thereby providing the user with a standard experience for such calling scenarios in Android mobile apps.

The notification is bound to a full-screen Activity that’s displayed when the mobile device is inactive. It lets users answer or reject the call without having to open the app.

The screen’s colors are configurable. See the configuration properties in the com.unblu.mobiledevice.v2.client.core.MobileCallUiConfiguration group.

Notification handling

If your application is targeting API level 31 or higher, you must know there are now restrictions on activity background starts.

If your app wishes to use notifications through Unblu, make sure your activity with intent-filter ACTION_MAIN uses the tag launchMode with value singleInstance. In addition, you should also override its onNewIntent() method and pass in the intent’s bundle with the Unblu notification data by calling onNewIntent. This avoids activity recreation from notification clicks that are not flagged for this purpose, while still channeling intent data from notification to the activity, ensuring no user experience is disrupted in the process.

Keyboard migration from SDK version 3 to SDK version 4

In version 3 of the Android mobile SDK, the lifecycle of the Unblu view (displaying, hiding, and handling of soft-layout overlays) was controlled internally by the SDK. In version 4, it’s up to the implementer of the SDK. This gives you more flexibility, but there may be circumstances where the Unblu view is overlaid by a soft keyboard at some point.

Such cases must be handled well to ensure a smooth user experience. The Google UI guide has a section on how to handle input method visibility. We recommend that you familiarize yourself with these guidelines to deal with the changes introduced in version 4 of the SDK.