Code setup and initialization

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

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

android.permission.MODIFY_AUDIO_SETTINGS: Required for audio as well as audio and video sessions.
android.permission.RECORD_AUDIO: Required for both audio and audio and video sessions.
android.permission.CAMERA: Required by for audio and video sessions.
android.permission.BLUETOOTH: Required by Vonage and LiveKit if a bluetooth device is used in calls.
android.permission.BROADCAST_STICKY: Required by Vonage and LiveKit.
android.permission.READ_PHONE_STATE: Required by Vonage and LiveKit so the SDK can react to incoming and outgoing calls.

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:

To create an UnbluVisitorClient instance, call Unblu.createVisitorClient. If you already have an instance of Android.app.Activity running, use the alternative Unblu.createVisitorClient method instead and pass the Activity as well.
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 instead and pass the Activity as well.

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 callModule = CallModuleProvider.create(); (1)
CallModule liveKitModule = LiveKitModuleProvider.create(); (2)
MobileCoBrowsingModule coBrowsingModule = MobileCoBrowsingModuleProvider.create();

1	For audio and video calls using the Vonage Video API
2	For audio and video calls using LiveKit

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:

Assign a token with the UnbluClientConfiguration.Builder.setOAuthToken method. 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, 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.

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.