Mobile SDK Android Integration
This section describes how the visitor/agent SDK can be integrated into an Android app. It describes step by step from adding the aar files to use the api, whereby it gives some hints to get a good user experience and avoid some common pitfalls.
Android Archive Integration
For android, unblu provides android archive (AAR) files for release and debug. Additionally some public sources are provides as .jars which contain also the JavaDoc of the public classes.
In total there are the following files:
Typically one would use the release aar files and add the public-sources jar files to get the JavaDoc in the IDE.
coresdk.aar needs to be added always.
Depending on the type of the app, if it should be for a visitor or for an agent, either the aar file for the visitor or agent sdk needs to be added too.
The easiest way to add the dependency to gradle is to use the android studio wizard. It can be found in File/Project Structure and must be executed ones for the coresdk and either the visitor or agentsdk files.
- To open the wizard click the green plus sign on the top left.
- In the wizard, select the Import .JAR/AAR Package section. After the path definition to the SDK AAR file is set, it is added as a module.
- In the app/Dependencies section of the Project Structure dialog you must define the dependency from the app to the SDK module. This can be done with the green plus on the right side and choosing Module dependency. Now the SDK is linked to the application.
The AAR files in android do not provide any javadoc information. To add this information, you must switch from the Android Project view to the Project view.
- Find the unblu SDK in the External Libraries section then right-click to open the Library Property.
After clicking the green plus, the path to the
unblusdk-public-sources.jarfile can be defined. Now the javadoc is available inside the IDE.
*-public-sources.jar files only contains the sources for the public API part and cannot be used as a library as it does not contain the internal classes.
The unblu SDKs use Firebase Cloud Messaging for push notifications. For Firebase to work correctly, it is necessary that the google-services.json file from the Firebase project is added to the app. Additionally you need to add the following line at the end of your app gradle file.
apply plugin: 'com.google.gms.google-services'
Please follow the instructions from here for detailed information.
Important to know is also, that it is not necessary to setup Firebase in your code. This is automatically done by the SDK when push notifications are enabled.
The following permissions are required in the applications manifest for different features.
|Permission Key||Required for Feature|
|android.permission.INTERNET||Required to use the internet connection|
|android.permission.SYSTEM_ALERT_WINDOW||Required to overlay the unblu UI on top of the application. This permission is automatically granted by the app store.|
|android.permission.RECORD_AUDIO||Required for audio and video sessions (also for plain audio sessions)|
|android.permission.CAMERA||Required for audio and video sessions|
|android.permission.MODIFY_AUDIO_SETTINGS||Required for audio and video sessions (also for plain audio sessions)|
|android.permission.WRITE_EXTERNAL_STORAGE||Required to save files which should be downloaded|
Code Setup and Initialization
In order to ensure the SDK works properly you must set the attribute
android:name in the
application tag of the
AndroidManifest.xml file to either
Alternately, to your own custom application class, which then inherits from one of the above classes.
See the code snippet below for an example.
"1.0" encoding="utf-8" xml version=<manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.unblu.testapp"> <application android:name="com.unblu.visitorsdk.UnbluVisitorApplication"> <!-- there a may also some other attributes --> </application> </manifest>
If this is not possible in your application, you can use the UnbluVisitorApplicationHelper or UnbluAgentApplicationHelper. They define a couple of static functions like UnbluVisitorApplicationHelper.onCreate-android.app.Application, 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 the one from the Application class. Additionally in the JavaDoc it is stated if the function needs to be called before or after the super call.
Unblu API Instance
Note: The UnbluApi is defined as a singleton, so there is only one instance of it.
Therefor further usages of the
instance member will not create additional instances.
Unblu API Configure
Before using the instance of the
UnbluAgentApi, it needs to be configured.
The api can be configured using the function
It accepts an instance of UnbluVisitorApiConfiguration/UnbluAgentApiConfiguration.
This class can 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 UnbluVisitorApiConfiguration/UnbluAgentApiConfiguration. There is only a very limited set of configurations which can be done on 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 configuration for the mobile visitor and agent SDK and also from configurations done for the webpage where unblu is integrated, we recommend to use different API Keys for each environment.
Inside the unblu API instance, only a copy of the configuration is stored.
So it can not be changed by the reference.
A new call to
configureApi has to be done.
Configuring the API can only be done while it is not initialized and it would throw an exception if it is already initialized.
Normally the configuration should only be done once at the beginning.
Before you initialize the API you should register for events in order to be sure not to miss any.
In android this can be done by using a custom implementation of UnbluVisitorEventReceiver for the visitor sdk and UnbluEventReceiver for the agent SDK.
Additionally for UI events a subclass of UnbluUiEventReceiver can be used.
An instance of such an receiver will register himself in the given context.
Therefore it should typically be instantiated inside the
Activity.onStart method and should be unregistered in the
Detailed information on the events can be found inside the IUnbluEventApiVisitor/IUnbluEventApi and UnbluUiEventApi class.
They also provides constants to get the values out of an
Intent if this is done manually without a subclass.
A very important event is the IUnbluUiEventApi.UiVisibilityRequest. As soon as push notifications are used, it is recommended to listen for this event. E.g. there is a push notification, when there is an incoming call. If the user opens the app by clicking the notification, the SDK directly will fire this event and assumes that the app will initialize and opens the unblu UI as soon as possible.
Initialization and Deinitialization
To initialize an instance of
UnbluAgentApi the function
initApi can be called.
The callback parameters can be used to get information about success and errors. Additionally the IUnbluEventApi.Error event can be used as described in the Events section. Regarding on errors it is highly recommended to register for the api error event globally to not miss an error as they can happen independent of an explicit call to the api.
After the success callback was triggered, the unblu UI can be displayed, new conversations can be started, agent availability can be checked etc…
The API can either be initialized directly or only on demand. For example when co-browsing is needed. Note that when the API is initialized on demand the SDK will take some time until it is ready and a session can be started. Additionally if push notifications are used, it is required at least once to have the API initialized. Otherwise the unblu collaboration server has no connection between a user and the device. Therefor in general we recommend to initialize the API as soon as it is possible (directly after login).
If the SDK is no longer needed and everything should get cleaned up, there is the UnbluCoreApi.deinitApi-com.unblu.coresdk.IUnbluApiSuccessVoidCallback-com.unblu.coresdk.IUnbluDeinitializeExceptionCallback function.
UnbluAgentSDK provides an unblu UI which shows all existing conversations and which can be used to chat and make a call inside a conversation.
This UI can be displayed on top of the app UI.
It is controlled also be using the instance of the
It is possible to open/close and change its top/bottom margin.
Additionally it can be checked if it is open or if a call is currently displayed.
For those states there are also events defined in the IUnbluUiEventApi.
If there is an issue with the unblu SDK, please be aware that the UI is rendered inside a
Therefor it is possible to attach the local Chrome to check if for error logs.
It is a limitation of the android WebViews that it is not possible to see the full content of logs inside the normal debugger console.
If, at some point, it is likely that the user would use the unblu UI, we would recommend you preload the UI. This can be achieved by either configuring to preload the UI with the initialization (see UnbluCoreApiConfiguration.setPreloadUiAfterApiInitEnabled-boolean) or by calling UnbluCoreApi.preloadUi-com.unblu.coresdk.IUnbluApiSuccessVoidCallback-com.unblu.coresdk.IUnbluApiNotInitializedExceptionCallback if the API was already initialized previously.
Next to the Unblu UI, the SDKs provide the class UnbluUiButton. This button UI can be placed inside the app UI either via xml or directly in the Code. Typically the button will be placed in the lower right corner of the screen.
The user can use the button to toggle the visibility of the unblu UI.
The button displays a number of unread chat messages when new messages arrive and the UI is hidden. Additionally it can automatically set the bottom margin for the unblu UI and places a semi transparent background behind it.
To integrate it, please follow the instructions in the UnbluUiButton class documentation.
The SDKs provides a simple way to add specific views which should not be shown on the remote side.
To do this, the
UnbluAgentApi provides the function UnbluCoreApi.addPrivateView-int which takes an id.
Each view as his own id.
After a view id is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. It is also possible to make a view visible to the remote side again by calling the UnbluCoreApi.removePrivateView-int function.
It is possible to define custom cookies, which should be sent with each request to the unblu server. This can either be done (initially) by using the UnbluCoreApiConfiguration.setCustomCookies-java.util.Map or by setting the the cookies dynamically via the UnbluCoreApi.setCustomCookies-java.util.Map 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 de-initialized. If the API is then initialized again, only the last defined cookies are used again.
A named area can either be set via the UnbluCoreApiConfiguration.setNamedArea-java.lang.String before initializing the API.
Or else it can be set by calling UnbluCoreApi.setNamedArea-java.lang.String on the
If a named area is set before initializing the API, also the specific configuration for it is loaded on initialization. If it is later set, 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 consequence, it is important to know if there will be specific configuration on the named area scope. In this case the named area has to be configured/set in the SDK before initializing the API, but then it should be always considered to change the configuration on API Key level. If a named area are only used for the queue, it can be set at any time before starting a new conversation.