Unblu Android mobile SDK: migrating from version 3 to version 4
When you migrate from version 3 to version 4 of the Unblu mobile SDK, you have to make a number of changes to your code.
This article describes the changes for Android. For iOS, please read the article on Unblu iOS 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 use a version of Android below 7.0, you will need to update your project to a minimum API level of 24 (android:minSdkVersion="24") or Unblu won’t run.
Installation
| Before you add the new frameworks, you should remove the old frameworks from your project. We recommend that you 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:
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)
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 |
visitorsdk and agentsdk are no longer dependencies; both are now part of the coresdk dependency.
UnbluApplication replaces UnbluVisitorApplication and UnbluAgentApplication
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.
/*
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 superseded 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 your UnbluClientConfiguration.Builder when you build 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 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, please refer to the documentation for the following types:
Initialization
UnbluVisitorApi and UnbluAgentApi are no longer static instances that can be initialized. The following code from version 3 will not 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:
/*
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 are not 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 will look something like this:
/*
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 will look something like this:
/*
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 enables 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:
/*
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) {
}
});How you position the mainView within your app is entirely up to you.
Because there is no longer a call to showUi(true/false), Unblu no longer knows for sure when it is visible in your app. You will therefore need to implement your own logic to add the mainView to your UI as well as to show and hide it.
New type for conversations
In version 4 of the UNblu mobile SDK, there’s a new type that represents a specific conversation, UnbluConversation. You can now always retrieve the currently open conversation using the UnbluVisitorClient.getOpenConversationValue and UnbluAgentClient.getOpenConversationValue getters.
Additionally, when a conversation is opened or closed, Unblu triggers the Observable unbluVisitorClient.getOpenConversation() and unbluAgentClient.getOpenConversation(). Subscribe to this Observable to be notified when the currently open conversation changes.
For more information about the available Observables, please review the Android mobile SDK reference.
Creating modules
UnbluCallModuleApi is now CallModule. There is a new Observable called CallModule.startMobileCoBrowsing().
UnbluCoBrowsingModuleApi is now MobileCobrowsingModule.
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 via Broadcast Receivers. Now, Unblu contains a dependency on RxJava which handles events and manages data. This means events are now dispatched via Observables that you can subscribe to.
For example, the following code would be used to subscribe 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. For a full list of Observables you can subscribe to, please refer to the Android mobile SDK reference.
For more information on Observables and on reactive programming in general, please refer to the description of Observables in the ReactiveX documentation.
The replacements for broadcast receivers are listed below.
| Version 3 | Version 4 |
|---|---|
|
deprecated |
|
deprecated |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
deprecated |
|
deprecated |
|
deprecated |
|
|
|
|
Other renamed or deprecated properties and methods
| Version 3 | Version 4 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
|
|
|
|
deprecated |