Contact usRequest a demo

Code setup and initialization

This article describes what you need to do so you can start to integrate Unblu features into your Android app.

Android manifest file

The Unblu Android mobile SDK requires several a number of changes to your app’s Android manifest file.

Set android:name to UnbluApplication or use UnbluApplicationHelper in Application class

For the SDK to work, you must set the attribute android:name in the application tag of the AndroidManifest.xml file to com.unblu.sdk.core.application.UnbluApplication. If you implemented your own custom application class that inherits from UnbluApplication, set the attribute to that instead.

Listing 1. AndroidManifest.xml example with default setting for android:name attribute 
<?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 Your app may also require other attributes

If you can’t use UnbluApplication or a subclass of it in your application, use the UnbluApplicationHelper class. It defines static methods such onCreate that you must call in the corresponding functions of your Application class.

The names of the methods in the helper class are the same as those in the Application class. The reference documentation states if you must call the method of the helper class before the super call.

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.

Permissions

Different Unblu features require you to add certain permissions to your application’s manifest.

  • android.permission.INTERNET: Required to use the internet connection.

  • android.permission.WRITE_EXTERNAL_STORAGE: Required to save downloaded files, for example in an Unblu live chat, if you use the default implementation of the UnbluDownloadHandler. If you provide your own custom implementation, the required permissions are up to you.

  • android.permission.WAKE_LOCK: Required to keep the device on during calls and mobile co-browsing sessions.

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

  • android.permission.READ_MEDIA_VISUAL_USER_SELECTED: Required for file uploads.

  • android.permission.RECORD_AUDIO: Required for both audio only and audio and video sessions, as well as for making audio recordings directly from within your app.

  • android.permission.CAMERA: Required for audio and video sessions as well as for taking pictures and/or videos directly from within your app.

  • android.permission.SYSTEM_ALERT_WINDOW: Most apps don’t need this permission. It’s only required if you want the active conversation indicator and co-browsing indicator to appear on top of any kind of dialog, including system dialogs. Without it, the indicators appear on the uppermost application level.

    Note that this permission requires user consent. You should therefore redirect the user to the settings page to grant this permission if you need it. For more information, refer to the Android documentation.

  • android.permission.VIBRATE: Required to notify users of incoming calls and for haptic effects on some navigation elements.

The following permissions are only required if you want to integrate Unblu’s audio and video call feature in your app:

  • android.permission.MODIFY_AUDIO_SETTINGS: Required for both audio only and audio and video sessions.

  • android.permission.BLUETOOTH: Required by LiveKit and Vonage if a bluetooth device is used in calls.

  • android.permission.BROADCAST_STICKY: Required by LiveKit and Vonage.

  • android.permission.READ_PHONE_STATE: Required by LiveKit and Vonage so the SDK can react to incoming and outgoing calls.

Starting with version 4.10.7, the Android mobile SDK no longer requires the permissions android.permission.READ_MEDIA_IMAGES and android.permission.READ_MEDIA_VIDEO. They’re no longer included in the SDK’s AndroidManifest.xml file. This change was made to conform to Google Play’s Photo and Video Permissions policy.

If a user permanently denies access to the camera, microphone, or speakers when the SDK requests it, the SDK doesn’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.

Unblu client instance

You can only ever have one initialized client instance running at any time throughout your application’s lifecycle.

The most important class instances of the SDK are UnbluVisitorClient and UnbluAgentClient. Choose the one that best matches your app’s intended users.

You can obtain an instance of either client class from the Unblu class:

Once the success callback is triggered, the UnbluVisitorClient or UnbluAgentClient instance is provided. With the client instance, you can obtain the Unblu View, add it to a view tree hierarchy, and display it. Your app also has access to Unblu’s features, such as starting a conversation or checking an agent’s availability.

When to create an Unblu client instance

You can create an Unblu client instance upfront so it’s available when needed, or you can create it on demand, for example when you want to start mobile co-browsing. When deciding when to create an client instance, take the following points into consideration:

  • The Unblu Android mobile SDK takes some time until it’s ready and you can start using it. Creating the client instance on demand may therefore result in a less satisfactory user experience.

  • If you create the client instance on demand, you must use the method that requires passing in an Android.app.Activity.

  • For push notifications from Unblu to work, you must initialize a client instance at least once. Without it, the Unblu Collaboration Server can’t associate the device with a particular user. To ensure push notifications work the way users expect them to, you should therefore instantiate a client as soon as you know which user is running your app, for example, right after they log in.

Unblu client configuration

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

The reference documentation for UnbluClientConfiguration.Builder describes the configuration options and their effects.

Only a limited number of settings are configurable via the Unblu SDK. All settings that are independent of the client (the app) can be done via the Unblu xref../../../knowledge-base/guides/ui/account-configuration-interface-guide.adoc[Account Configuration interface^].

The recommended way to separate the settings for different environments—​such as visitor and agent mobile apps, or the website Unblu is integrated in—​is to use different API keys for each environment.

The configuration is only used when creating new instances of UnbluVisitorClient and UnbluAgentClient. Once you’ve created a client instance, you can’t change its configuration. If you want to do so, you must destroy the current client instance and create a new one and pass it a new UnbluClientConfiguration with the new settings.

Modules

The Unblu Android mobile SDK is divided into modules. Depending on the features you want to implement in your app, you may need all or only some of them.

To use a module, you must register it in the UnbluClientConfiguration by calling `UnbluClientConfiguration.Builder.registerModule(UnbluModule). When you no longer need the module, you can unregister it with a call to `UnbluClientConfiguration.Builder.unregisterModule(UnbluModule).

Each module has an associated provider class. To use a module in your app, create an instance of it with its provider class:

CallModule liveKitModule = LiveKitModuleProvider.create(); (1)
CallModule callModule = CallModuleProvider.create(); (2)
MobileCoBrowsingModule coBrowsingModule = MobileCoBrowsingModuleProvider.create();
1 For audio and video calls using LiveKit
2 For audio and video calls using the Vonage Video API

Authentication

If you need to pass authentication information to the Unblu Android mobile SDK, either call the UnbluClientConfiguration.Builder.setAccessToken method or set custom cookies as described in 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 token is used in two distinct stages:

  1. Assign a token with the UnbluClientConfiguration.Builder.setOAuthToken method. You must pass the token before calling Unblu.createAgentClient() or Unblu.createVisitorClient().

  2. 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, the Unblu.onError method emits an ErrorData with the error type UnbluClientErrorType#AUTHORIZATION. In this case, stop the API, assign a valid token, and restart the API.

The service worker that sets the authorization header on all requests must be excluded from any firewall rules you have in place. This is to ensure that it’s accessible even when the header isn’t present. The URL to exclude is /unblu/sw/auth-header/v1/auth-header-sw.js.

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 so you don’t miss any.

The Unblu class has a number of observables you can subscribe to. You should at least subscribe to the Unblu.onError observable, as it can also inform you of errors that occur independently of any explicit calls to the API.

You can obtain events related to the client instance and subscribe to them by calling the instance itself. Most observables related to client instances are defined in UnbluClient, but UnbluVisitorClient has some additional observables.

For more information on the observable events, refer to the reference documentation for Unblu, UnbluClient, and UnbluVisitorClient.

Activity launch modes and intent flags

The Unblu Android mobile SDK doesn’t know how its host app arranges its back stack. To ensure its activities fit into the host app’s navigation smoothly, the SDK mostly uses default launch modes and minimal flags. Choose a launch mode for your app based on the explanations below.

If the host app doesn’t explicitly specify a launch mode for an activity provided by the SDK, the launch mode defined in the SDK’s manifest is used. If it does specify a launch mode—​even if it’s an activity defined by the SDK--,the host app’s launch mode overrides that of the SDK.

The Unblu Android mobile SDK has three types of activity:

  • File upload dialog

    This activity works best in a normal back stack, so the Unblu Android mobile SDK doesn’t use any special flags.

    Sticking to the standard launch mode provides a smooth and predictable experience. Using singleTask or singleInstance might push the activity to the background or reorder tasks after the user picks a file.

  • Incoming call UI

    For this type of activity, the Unblu Android mobile SDK uses the FLAG_ACTIVITY_SINGLE_TOP or FLAG_ACTIVITY_NEW_TASK intent flags. That way, tapping a "ringing" notification brings the existing call screen to the foreground instead of creating multiple call screens.

    The SDK doesn’t use the FLAG_ACTIVITY_CLEAR_TASK intent flag because it clears all other activities in the task. This disrupts the host app’s flow.

    On some Android versions, launching an activity from the background typically requires either the FLAG_ACTIVITY_NEW_TASK intent flag or a foreground service.

  • Notification-driven activities

    The Unblu Android mobile SDK uses the FLAG_ACTIVITY_CLEAR_TOP intent flag to bring an existing instance of the activity to the foreground.

Deinitialization

It’s possible to deinitialize UnbluVisitorClient and UnbluAgentClient instances.

If your app no longer needs the Unblu Android mobile SDK, call the UnbluClient.deinitClient method to clean up. Use the callback parameters to get information about any errors.

See also