Code setup and initialization
This article describes what you need to do so you can start to integrate Unblu features into your Android app.
The Unblu Android mobile SDK requires several a number of changes to your app’s Android manifest file.
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.
AndroidManifest.xml example with default setting for
<?xml version="1.0" encoding="utf-8"?>
|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
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
Different Unblu features require you to add certain permissions to your application’s manifest.
Required to use the internet connection.
Required to save downloaded files, for example in an Unblu live chat.
Required to keep the device on during calls and mobile co-browsing sessions.
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:
Required for audio as well as audio and video sessions.
Required for both audio and audio and video sessions.
Required by for audio and video sessions.
Required by Vonage and LiveKit if a bluetooth device is used in calls.
Required by Vonage and LiveKit.
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.
You can only ever have one initialized client instance running at any time throughout your application’s lifecycle.
You can obtain an instance of either client class from the
To create an
Unblu.createVisitorClient. If you already have an instance of
Android.app.Activityrunning, use the
alternative Unblu.createVisitorClientmethod instead and pass the
To create an
Unblu.createAgentClient. If you already have an instance of
Android.app.Activityrunning, use the
alternative Unblu.createAgentClientmethod instead and pass the
success callback is triggered, the
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.
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
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.
When you create an instance of
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
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.
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();
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.setOAuthTokenmethod. You must pass the token before calling
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.
| 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
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.
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.
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
UnbluVisitorClient has some additional observables.
It’s possible to deinitialize
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.
For more information on the configuration option for the Unblu clients, refer to the reference documentation for