Unblu Android mobile SDK: migrating from version 3 to version 4

Requirements

The minimum version of the Android OS supported by Unblu is Android 7.0. If your project currently supports a version of Android below 7.0, you need to update your project to a minimum API level of 24 (android:minSdkVersion="24") for Unblu to run.

Installation

Before you add the new frameworks, remove the old frameworks from your project. You should then clean your Android project and sync your Gradle dependencies to make sure all references are updated.

To install the SDK, add the dependencies you need (SDK and modules) to your application’s build.gradle file:

Listing 1. build.gradle with Unblu and other dependencies

dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    testImplementation 'junit:junit:4.13'

    implementation "com.airbnb.android:lottie:$lottieVersion"
    implementation 'androidx.appcompat:appcompat:1.3.1'
    implementation 'com.google.android.material:material:1.4.0'

    implementation 'com.unblu.mobile-sdk-android:coresdk:4.x.x' (1)(2)
    implementation 'com.unblu.mobile-sdk-android:callmodule:4.x.x' (1)
    implementation 'com.unblu.mobile-sdk-android:mobilecobrowsingmodule:4.x.x' (1)
    implementation 'com.unblu.mobile-sdk-android:firebasenotificationmodule:4.x.x' (1)
}

1	Unblu-related dependencies; replace `4.x.x` with the specific build version you want to use
2	`visitorsdk` and `agentsdk` are no longer dependencies; both are now part of the `coresdk` dependency.

`UnbluApplication` replaces `UnbluVisitorApplication` and `UnbluAgentApplication`

The UnbluVisitorApplication and UnbluAgentApplication classes have been superseded by the UnbluApplication class. Take this change into account in your AndroidManifest.xml file:

Listing 2. Manifest excerpts with UnbluApplication, UnbluVisitorApplication, and UnbluAgentApplication

<!-- Version 3 -->

<application
    android:name="com.unblu.sdk.visitor.UnbluVisitorApplication"
    .../>

<application
    android:name="com.unblu.sdk.visitor.UnbluAgentApplication"
    .../>

<!-- Version 4 -->

<application
    android:name="com.unblu.sdk.core.application.UnbluApplication"
    .../>

`UnbluClientConfiguration` replaces `UnbluApiConfiguration`

Unblu is still initialized using a configuration object. However, the name of the relevant class has changed from UnbluApiConfiguration to UnbluClientConfiguration:

Listing 3. Initializing the configuration object

/*
    Version 3
*/
new UnbluApiConfiguration.Builder(
        "http://www.example.com/?val=argument",
        "<your-API-key>", (1)
        UnbluPreferencesStorage.createSharedPreferencesStorage(context()),
        UnbluDownloadHandler.createExternalStorageDownloadHandler(context())
    ).build();

/*
    Version 4
*/
new UnbluClientConfiguration.Builder(
        "http://www.example.com/?val=argument",
        "<your-API-key>", (1)
        UnbluPreferencesStorage.createSharedPreferencesStorage(getApplicationContext()),
        UnbluDownloadHandler.createExternalStorageDownloadHandler(getApplicationContext()),
        new UnbluPatternMatchingExternalLinkHandler()
    ).build();

1	Replace `<your-API-key>` with your API key

The properties of UnbluClientConfiguration are largely the same as those of UnbluApiConfiguration, except with regard to the handling of external links. The externalLinkPatternWhitelist property is no longer available. It has been replaced by the externalLinkHandler property and the new UnbluExternalLinkHandler interface.

When you initialize UnbluClientConfiguration, you must provide an implementation of the UnbluExternalLinkHandler interface. Unblu provides a default implementation, UnbluPatternMatchingExternalLinkHandler. To use the default implementation, pass a new instance of it to the UnbluClientConfiguration.Builder when building your UnbluClientConfiguration.

UnbluPatternMatchingExternalLinkHandler has two constructors, one of which takes a List<Pattern> argument. This can be used to provide the link handler with patterns against which to check external links.

When a link is tapped in a conversation, Unblu calls the method decidePolicy(for: URL) → UnbluExternalLinkHandlingPolicy on the UnbluExternalLinkHandler. How Unblu proceeds depends on whether the method returns UnbluExternalLinkHandlingPolicy.OPEN or UnbluExternalLinkHandlingPolicy.BLOCK.

UnbluClientConfiguration exposes the link handler via the new externalLinkHandler property.

For more information, refer to reference documentation:

Initialization

UnbluVisitorApi and UnbluAgentApi are no longer static instances that can be initialized. For example, the following code from version 3 won’t work with version 4:

/*
    Version 3
*/
UnbluVisitorApi unbluApi = UnbluVisitorApi.getInstance();
UnbluApiConfiguration config = createUnbluConfig();
unbluApi.configureApi(config);
unbluApi.initApi();

Instead, version 4 of the Unblu Android mobile SDK provides a static helper class, Unblu, for creating an initialized instance of the Unblu client. There are two signatures for creating agent and visitor instances of UnbluClient:

Listing 4. Signatures of methods for creating instances of UnbluAgentClient and UnbluVisitorClient

/*
    Version 4
*/
public static void createVisitorClient(final Application application,
                                       final Activity activity, (1)
                                       final UnbluClientConfiguration unbluClientConfiguration,
                                       final UnbluNotificationApi notificationApi,
                                       @Nullable
                                       final InitializeSuccessCallback<UnbluVisitorClient> success,
                                       @Nullable
                                       final InitializeExceptionCallback failure)

public static void createVisitorClient(final Application application,
                                       final UnbluClientConfiguration unbluClientConfiguration,
                                       final UnbluNotificationApi notificationApi,
                                       @Nullable
                                       final InitializeSuccessCallback<UnbluVisitorClient> success,
                                       @Nullable
                                       final InitializeExceptionCallback failure)

public static void createAgentClient(final Application application,
                                     final Activity activity, (1)
                                     final UnbluClientConfiguration unbluClientConfiguration,
                                     final UnbluNotificationApi notificationApi,
                                     @Nullable
                                     final InitializeSuccessCallback<UnbluAgentClient> success,
                                     @Nullable
                                     final InitializeExceptionCallback failure)

public static void createAgentClient(final Application application,
                                     final UnbluClientConfiguration unbluClientConfiguration,
                                     final UnbluNotificationApi notificationApi,
                                     @Nullable
                                     final InitializeSuccessCallback<UnbluAgentClient> success,
                                     @Nullable
                                     final InitializeExceptionCallback failure)

1	If you aren’t extending your Application class from `UnbluApplication`, you must provide the Activity which is currently active. Otherwise, you can use the other signature.

To create a visitor client, your code might look like this:

Listing 5. Code creating an UnbluVisitorClient instance

/*
    Version 4
*/
Unblu.createVisitorClient(application,
        activity,
        unbluConfiguration,
        unbluNotificationApi,
        new InitializeSuccessCallback<UnbluVisitorClient>() {
            @Override
            public void onSuccess(@Nullable UnbluVisitorClient instance) {
                (1)
            }

            @Override
            public void onPreloadSuccess() {

            }
        },
        new InitializeExceptionCallback() {
            @Override
            public void onConfigureNotCalled() {

            }

            @Override
            public void onInErrorState() {

            }

            @Override
            public void onInitFailed() {

            }
        });

1	Here you get your instance of `UnbluVisitorClient`.

For an agent client, your code might look something like this:

Listing 6. Code creating an UnbluAgentClient instance

/*
    Version 4
*/
Unblu.createAgentClient(application,
        activity,
        unbluConfiguration,
        unbluNotificationApi,
        new InitializeSuccessCallback<UnbluAgentClient>() {
            @Override
            public void onSuccess(@Nullable UnbluAgentClient instance) {
                (1)
            }

            @Override
            public void onPreloadSuccess() {

            }
        },
        new InitializeExceptionCallback() {
            @Override
            public void onConfigureNotCalled() {

            }

            @Override
            public void onInErrorState() {

            }

            @Override
            public void onInitFailed() {

            }
        });

1	Here you get your instance of `UnbluAgentClient`.

Notification API

During initialization, you must now provide an implementation of UnbluNotificationApi. To use the default implementation, call UnbluNotificationApi.createNotificationApi().

Unblu `View`

In the Unblu mobile SDK v3, all Unblu UI content was rendered in a View. The View was managed internally by Unblu and was displayed on top of the application. To show the Unblu UI, you had to call showUi(true/false) explicitly.

Now, Unblu provides a View into which the entire Unblu UI is rendered. This makes integrating Unblu into your application simpler and provides a greater degree of control over where the Unblu UI appears in your app.

The View is available as a property of the Unblu instance. A typical approach is to add the Unblu View to your layout after you create it:

Listing 7. Adding the Unblu View to a layout

/*
    Version 4
*/
Unblu.createVisitorClient(this,
        activity,
        unbluConfiguration,
        notificationApi,
        new InitializeSuccessCallback<UnbluVisitorClient>() {
            @Override
            public void onSuccess(@Nullable UnbluVisitorClient instance) {
                Toast.makeText(UnbluDemoApplication.this, "UnbluApi initialized!", Toast.LENGTH_SHORT).show();
                unbluVisitor = instance;

                //Add the view to the desired layout
                layoutContainer.addView(unbluVisitor.getMainView(),
                        new ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT));

                //...
            }
            @Override
            public void onPreloadSuccess() {
          }
        },
        new InitializeExceptionCallback() {
            @Override
            public void onConfigureNotCalled() {
            }
            @Override
            public void onInErrorState() {
            }
            @Override
            public void onInitFailed(@NonNull UnbluClientErrorType errorType, @Nullable String details) {

            }
        });

Because there’s no longer a call to showUi(true/false), Unblu doesn’t know when it’s visible in your app. You must therefore implement your own logic to add the mainView obtained by calling UnbluClient.getMainView() to your UI as well as to show and hide it.

How you position the mainView within your app is up to you.

New type for conversations: `UnbluConversation`

There’s a new type that represents Unblu conversations, UnbluConversation. You can now always retrieve the conversation that’s currently open by calling getOpenConversationValue on your UnbluVisitorClient or UnbluAgentClient instance.

Additionally, when a conversation is opened or closed, Unblu triggers the Observable getOpenConversation() on the UnbluVisitorClient or UnbluAgentClient. Subscribe to this Observable to be notified when the conversation that’s currently open changes.

For more information about the available Observables, refer to the Android mobile SDK reference.

Creating modules

UnbluCallModuleApi is now CallModule. There’s a new Observable called CallModule.isCallActive().

UnbluCoBrowsingModuleApi is now MobileCobrowsingModule.

Listing 8. Creating instances of CallModule and MobileCobrowsingModule

/*
    Version 3
*/
callModule = UnbluCallModule.getModule();
coBrowsingModule = UnbluCobrowsingModule.getModule();

/*
    Version 4
*/
callModule = CallModuleProvider.create();
coBrowsingModule = MobileCobrowsingModuleProvider.create();

Unblu events

In version 3 of the Unblu mobile SDK, events were dispatched using broadcast receivers. Now, Unblu contains a dependency on RxJava to handle event and manage data. Events are now dispatched using Observables that you can subscribe to. For example, the following code shows how subscribing to an API event has changed:

Listing 9. Subscribing to an API event

/*
    Version 3
*/
UnbluVisitorEventReceiver unbluBroadcastReceiver = new UnbluVisitorEventReceiver(getApplicationContext()) {
        @Override
        protected void onApiIsInitialized(boolean isInitialized) {
                //...
        }
  //...
}

/*
    Version 4
*/
Unblu.onVisitorInitialized()
                .subscribeOn(Schedulers.io())
                .observeOn(AndroidSchedulers.mainThread())
                .doOnError(throwable -> Log.d("error"))
                .subscribe(visitorClient -> {
               	        //...
                });

unbluClient.getOpenConversation()
                .subscribeOn(Schedulers.io())
                .observeOn(AndroidSchedulers.mainThread())
                .subscribe(unbluConversation -> {
                        //...
                });

The initialized agent and visitor clients and the Unblu static helper class all provide a number of Observables. The Observables you can subscribe to are described the Android mobile SDK reference.

For more information on Observables and on reactive programming in general, refer to the description of Observables in the ReactiveX documentation.

The replacement for each broadcast receiver is listed below.

Table 1. List of replacements for broadcast receivers in Unblu Android mobile SDK version 4
Version 3	Version 4
`UnbluVisitorEventReceiver`	deprecated
`UnbluVisitorEventReceiver.onNotification()`	`UnbluNotificationApi.onMessageReceived()`
`UnbluVisitorEventReceiver.onApiIsInitialized()`	`Unblu.onVisitorInitialized()` and `Unblu.onAgentInitialized()`
`UnbluVisitorEventReceiver.onPersonChanged()`	`UnbluClient.onPersonChanged()`
`UnbluVisitorEventReceiver.onAgentAvailable()`	`UnbluVisitorClient.isAgentAvailable()`
`UnbluVisitorEventReceiver.onUnreadMessagesCountChanged()`	`UnbluClient.onUnreadMessagesCountChanged()`
`UnbluVisitorEventReceiver.onUiPreloaded()`	`UnbluClient.onUiPreloaded()`
`UnbluVisitorEventReceiver.onPersonChanged()`	`UnbluClient.onPersonChanged()`
`UnbluVisitorEventReceiver.onUiReady()`	`UnbluClient.onUiReady()`
`UnbluVisitorEventReceiver.onError()`	`Unblu.onError()`
`UnbluUiEventReceiver`	deprecated
`UnbluUiEventReceiver.onUiIsVisible`	deprecated
`UnbluUiEventReceiver.onUiVisibilityTransition()`	deprecated
`UnbluUiEventReceiver.onUiVisibilityRequest()`	`Unblu.onUiVisibilityRequest()`
`UnbluUiEventReceiver.onUiHideRequest()`	`Unblu.onUiHideRequest()`

Other renamed or deprecated properties and methods

Below is an overview of properties and methods that have been renamed or deprecated in version 4 of the Unblu Android mobile SDK.

Table 2. Renamed and deprecated properties and methods
Version 3	Version 4
`UnbluVisitorApi.instance.startAudioCall()`	`UnbluConversation.startAudioCall()`
`UnbluVisitorApi.instance.startVideoCall()`	`UnbluConversation.startVideoCall()`
`UnbluVisitorApi.instance.isCallUiOpen()`	`UnbluConversation.isCallUiOpenValue()`
`UnbluVisitorApi.enableDebugOutput`	`Unblu.enableDebugOutput`
`UnbluVisitorApi.enableCapturingPerformanceLogging`	`Unblu.enableCapturingPerformanceLogging`
`UnbluVisitorApi.logLevel`	`Unblu.setLogLevel()`
`UnbluVisitorApi.getInstance().showUi()`	deprecated
`UnbluVisitorApi.getInstance().preloadUi()`	deprecated
`UnbluVisitorApi.getInstance().isUiVisible`	deprecated
`UnbluVisitorApi.getInstance().setUiMargins`	deprecated
`UnbluVisitorApi.getInstance().uiBottomMargin`	deprecated
`UnbluVisitorApi.getInstance().uiTopMargin`	deprecated
`UnbluCoBrowsingModuleApi.stopMobileCoBrowsing()`	`UnbluConversation.stopMobileCoBrowsing()`
`UnbluCoBrowsingModuleApi.isMobileCoBrowsingActive()`	`UnbluConversation.isMobileCoBrowsingActive()`
`UnbluCoBrowsingModuleApi.setScreenCapturer()`	deprecated

Keyboard migration from SDK version 3 to SDK version 4

In version 3 of the Android mobile SDK, the lifecycle of the Unblu view (displaying, hiding, and handling of soft-layout overlays) was controlled internally by the SDK. In version 4, it’s up to the implementer of the SDK. This gives you more flexibility, but there may be circumstances where the Unblu view is overlaid by a soft keyboard at some point.

Such cases must be handled well to ensure a smooth user experience. The Google UI guide has a section on how to handle input method visibility. We recommend that you familiarize yourself with these guidelines to deal with the changes introduced in version 4 of the SDK.