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 Observable
s, 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 Observable
s 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 Observable
s. For a full list of Observable
s 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 Observable
s 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 |