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.
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, callUnblu.createVisitorClient
. If you already have an instance ofAndroid.app.Activity
running, use thealternative Unblu.createVisitorClient
method instead and pass theActivity
as well. -
To create an
UnbluAgentClient
instance, callUnblu.createAgentClient
. If you already have an instance ofAndroid.app.Activity
running, use thealternative Unblu.createAgentClient
method instead and pass theActivity
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 callingUnblu.createAgentClient()
orUnblu.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.
See also
-
For more information on the different Unblu clients, refer to the Unblu Android mobile SDK reference for
UnbluClient
,UnbluVisitorClient
, andUnbluAgentClient
. -
For more information on the configuration option for the Unblu clients, refer to the reference documentation for
UnbluClientConfiguration
. -
For more information on the observer pattern as implemented by RxJava, refer to the ReactiveX documentation.