Mobile SDK

To go directly to the mobile SDK documentation:

Android Mobile SDK

iOS Mobile SDK

Introduction

unblu provides an SDK for your visitors' mobile applications; available for both iOS and Android. When the unblu mobile SDK is integrated into an app, the app can be co-browsed together with the agent desk. The features of the mobile SDK and the integration of the SDK into a customer app are described here.

Note: If you need instructions on how agents deal with visitors using mobile see the Mobile Agent User Guide.

System Requirements

See Mobile SDK Requirements.

Features

The following features can be used when interacting with the SDK:

• Dynamically de-/initialize the API
• Check if the SDK has connected to the collaboration server
• Check if a session is active
• Start a chat session
• Start a co-browsing session
• Check if an agent is available
• Adding/Removing private views, which should not be displayed to the agent (e.g., password fields)
• Add/update custom cookies which are sent with each request to the unblu server
• Events for API state, session state, notifications (e.g., agent/visitor joint messages, chat messages), errors. (More details can be found in the code documentation which is provided together with the SDK for each platform.)

The following features are automatically available in co-browsing sessions:

• Co-browsing all content of the app
• Agent can see interactions of the visitor with the screen
• Agent can mark areas for the visitor inside the app
• Chat between visitor and agent inclusive UI
• Orientation changes are displayed on the agent side
• Lock screen displayed on agent desk, if the visitor puts the app into the background.

Configuration on the collaboration server

The following configuration is required to be set inside the collaboration server.

Integration

This section describes how the SDK can be integrated into an app, starting with adding the SDK code to the app. It also shows how the SDK should be used to start sessions, and it adds additional notes for the best possible integration into an app.

iOS Framework Integration

unblu provides different framework files. For example, there is a so-called fat framework, which contains the SDK for all required platforms (x86 simulator and ARM real device).

This 'fat framework' file should be used most of the time. However, for a release in the Apple AppStore the x86 framework should be removed using Apple's "lipo" tool.

There are several scripts on the internet that can be used to strip the simulator part away while building the app. If this is not desired, unblu also provides two additional framework files. One (only) for the simulator platform and one for real devices.

To integrate the SDK, the framework needs to be dragged into Xcode. Then you must add the SDK framework to the app configuration in General > Embedded Binaries.

Note: This documentation only shows you how to use the SDK by using Swift (and not with Objective-C) as this is the new standard from Apple. Nevertheless, the SDK is also compatible with Objective-C.

To use elements from the SDK you must perform an import at the beginning of the file where you use the API of the SDK: import UnbluSDK.

unblu Mobile SDK - Swift - Xcode - Compatibility

In 2014 Apple wrote : "... if your project uses frameworks to share code with an embedded extension, you will want to build the frameworks, app, and extensions together. It would be dangerous to rely upon binary frameworks that use Swift — especially from third parties. As Swift changes, those frameworks will be incompatible with the rest of your app. When the binary interface stabilizes in a year or two, the Swift runtime will become part of the host OS and this limitation will no longer exist."

The binary interface has not, unfortunately, 'stabilized' yet. This means you must take care that you use the correct versions of our mobile SDK with compatible Swift versions.

This also means that users of the unblu mobile SDK may have to update their unblu mobile SDK library when Apple updates Swift.

Use the table below for the right combination of software versions:

Note: The only way to solve this (if there is a compatibility problem with your current mobile SDK implementation) is for us to supply you with a compatible version of our mobile SDK. This is an issue that may or may not occur some time in the future and, given that Apple are dragging their feet regarding backwards compatibility, it is not possible for us to predict if, or when, that could happen.

SDK initialization

It is highly recommended to get an instance of the UnbluApi class inside the AppDelegate.application function by calling UnbluApi.instance. In this way the SDK can register itself for all required events before one of them is fired.

Note: The UnbluApi is defined as a singleton, so there is only one instance of it.

Android Archive Integration

For android, unblu provides an android archive (AAR) file for release and debug. If android studio is used, the build environment uses gradle. The easiest way to add the dependency to gradle is to use the android studio wizard. It can be found in File/Project Structure.

1. To open the wizard click the green plus sign on the top left.

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

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

4. 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.jar file can be defined. Now the javadoc is available inside the IDE.

Note: The unblusdk-public-sources.jar file only contains the sources for the public API part and cannot be used as a library as it does not contain the internal classes.

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 com.unblu.unblusdk.UnbluApplication. Alternately, to your own custom application class, which then inherits from the com.unblu.unblusdk.UnbluApplication class. See the code snippet below.

<?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.unblusdk.UnbluApplication"
        ...
        >
        </application>
</manifest>

If this is not possible in your application, you can use the UnbluApplicationHelper. It defines a couple of static functions like onCreate, 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.

Permissions

Permissions iOS

The following permissions are required in the applications info.plist for different features.

Permissions Android

In android the following permissions are always required and are already in the manifest of the SDK. Therefor they must not be added explicitly to the applications manifest file.

The following permissions are required in the applications manifest file for different features.

SDK usage

Configuration

As the SDK for Android and iOS are very similar or can easily be converted into each other, this documentation only refers to the iOS swift code. At points where a distinction is needed, it will be highlighted here in the documentation.

The most important class of the SDK is UnbluApi. It provides an instance function, which can be used to get an instance of the API.

First, the instance should be configured by calling the configureApi function. It accepts an instance of UnbluApiConfiguration. This class can be instantiated with the base url of the unblu server and the API key of the unblu account. Also, other configuration can be done on this instance. Inside the unblu API 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 has only an effect as long as the API is not initialized and should not be called, when the API is initialized. Normally the configuration should only be done once at the beginning.

A different API key could be created for mobile within the unblu agent desk interface to do special configuration for the mobile application.

The API can either be initialized directly or 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. Note also that it would then not be possible to preload a chat ui. See the Performance section below for further details.

For examples of how to configure and start the SDK see the class definition of UnbluApi for android and the UnbluApi for iOS.

Note: It is not possible to check if agents are available without initializing the API.

Events

Before you initialize the API you should register for events in order to be sure not to miss any.

iOS

In iOS this can be done by using NotificationCenter. Inside the Notification.Name object all unblu events are available with "Unblu" as the prefix. Detailed information on the events can be found inside the UnbluEventApi class. It also provides constants to get the values out of the Notification.userInfo member.

Android

In android an UnbluEventReceiver can be used to register for unblu events. This should normally be done inside the Activity.onStart method and should be unregistered in the Activity.onStop. It is very important to use android.support.v4.content.LocalBroadcastManager as otherwise no events are received. See example code below.

    private UnbluEventReceiver unbluBroadcastReceiver;
    @Override
    protected void onStart() {
        super.onStart();
        unbluBroadcastReceiver = new UnbluEventReceiver(getApplicationContext()) {
            ...
        };
    }
    @Override
    protected void onStop() {
        LocalBroadcastManager.getInstance(getApplicationContext()).unregisterReceiver(unbluBroadcastReceiver);
        super.onStop();
    }

De-/Initialize the API

Now the API can be initialized. This can be done by calling the initApi function. Use the callback parameters to get information about success and errors.

After the API is ready, a session can be started and stopped and checks for available agents can be performed.

If the SDK is no longer needed and everything should get cleaned up, there is the deinitApi function.

Private Views

The SDK provides a simple way to add specific views which should not be shown a the agents side. To do this, the UnbluApi provides the function addPrivateView. This function takes an tag id on iOS, which can be defined for each view. On Android this function accepts a view id which is also definable for each view. After a view was added, it is automatically overlaid by an image before the screen is transmitted to the agent. It is also possible to make a view visible to the agent again by calling the removePrivateView function.

Custom Cookies

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 UnbluApiConfiguration or by setting the the cookies dynamically via the setCustomCookies 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 configured cookies are used again.

Named Areas

Similar to a web page, the named area feature is also available for the mobile SDK. See Named Area for more details.

A named area can either be set via the UnbluApiConfiguration at the very beginning or by calling setNamedAreaon the UnbluApi. 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 request in the agent desk queue in the way that the agent can filter by the named area. After a session is started, changing the named area has no effect.

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. If a named area are only used for the queue, it can be set at any time before starting a session.

Performance

There are three successive, and time-consuming, processes that must run before a collaboration session is fully started:

1. The initialization of the API.
2. The loading of the resources from the unblu server to start a session.
3. The handshake with the server to finally establish a session.

To prevent a bad user experience there are some different, possible, approaches to prevent long waiting times for the user.

During the initialization the API needs to load content from the unblu server, which needs time and also produces network traffic. In general, we recommend that you initialize the API as soon as possible to prevent long loading times when the user wants to start a session. The downside may be that there can be data loaded which is not needed if the user never starts a collaboration session. If there is some point in the application where it is highly predictable that the user will use unblu next, this could be a good place to initialize the API. So, you must carefully consider the exact point when the API should be initialized.

If, at some point, it is likely that the user would use chat, we would recommend you preload a chat UI by either configuring to preload a chat UI with the initialization (see UnbluApiConfiguration) or by calling UnbluApi.preloadChatUi if the API was already initialized previously. In this way the SDK will already load all required resources from the unblu server to start a chat session.

Starting a chat session is a very demanding task. Preloading the chat UI is a good point to prevent long loading times for the user. But starting a session still requires some time to do the handshake with the unblu server. As there is no way of doing this beforehand, the SDK will display a loading UI until the session is completely set up. There is a default UI provided by the SDK, but it is also possible to display a custom UI. To achieve this, a custom UI has to be given to the startChatSession function. There is also a callback parameter to retrieve the current state of the loading. In this way it is possible to display some progress to the user.

Additional Notes

If a session has been started via PIN and later a chat UI is needed, the call to start a chat session can be used. It will then not start a new chat session, but instead join the current session and display the UI for it.

Unblu Default UI

For an easier integration into an app, unblu provides a default UI to display a chat in an overlay. Additionally, unblu provides a custom button UI to show/hide a overlay UI. Here you see a screen shot of when the Overlay UI is displayed and the UnbluUiButton is used in the lower right corner.

Overlay UI

The overlay UI is a UI which is displayed above all content of the app. The overlay UI can be controlled by the class UnbluUiApi. This class is defined as a singleton. Therefore, there is only one overlaying UI in the whole application.

There are two possible ways to use the overlaying UI. First you can call enableUnbluUi. If the UI is enabled, it will create a chat UI (even if it is only a PIN session) as soon as a session starts. It will be removed after the session has ended. The second approach is to start a session via the function startChatSessionWithUi on the UnbluUiApi instance. It then automatically enables the UnbluUiApi and directly starts a new session and displays it. Remember: As it is then enabled, as soon as a new session is started the overlaying UI would display again.

To show and hide the overlaying UI without closing the session the function showChat can be used. You can use the function isChatVisible to check for its visibility.

To allow a button or other controls at the bottom, or the top, of the overlaying UI, it is possible to define a top and bottom margin on the UnbluUiApi instance. Using a value of 0 for the top margin already considers the top status bar. You would need to use a negative margin, if it should be placed above of the status bar.

To be aware of when the overlay UI shows or hides there are also some events for which you can register. There are more details about them in the UnbluUiEventApi.

The biggest benefit of the overlay UI is that the session inside must not be reloaded when switching the views inside the application. This is a particularly difficult task, in android, when switching between activities.

Button UI

The UnbluUiButton can be placed somewhere in your UI. It is only visible while a session is active. When it is pressed, it shows the overlay UI of the UnbluUiApi.

The button displays a number of unread chat messages when new messages arrive while the UI is hidden. As soon as an user opens the UI again, the counter is reset.

As the button is strong depending on the OS how to use it in your application, please go to UnbluUiButton for iOS and to UnbluUiButton for Android. There you will find a more detailed instruction how it can be integrated.

• deploycloud
• deployonprem