This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Unblu mobile SDK: migrating from version 2 to version 3

When you migrate from version 2 to version 3 of the Unblu mobile SDK, you have to make a number of changes to your code. This article describes these changes for iOS and Android.

Migrating to version 3 of the iOS mobile SDK

The minimum supported iOS version for Unblu mobile SDK 3 is iOS 12. If your project uses iOS 11 or older, you will need to update your project to a minimum iOS version of 12.0. Unblu will not be able to run otherwise.

Installation

Before you add the new frameworks, make sure to remove the old frameworks from your project. We recommend that you also clean your Xcode project after this to make sure that all references are updated.

In Unblu mobile SDK 3, the iOS SDK is now distributed as an XCFramework.

Installation is easy. Simply drag the XCFrameworks you require into your Xcode project, then add them to your target. When copying the XCFrameworks into your project, make sure to check the box Copy items if needed.

Firebase

In Unblu mobile SDK 3, some components such as Firebase are now in separate, optional modules. To continue using Firebase for Unblu push notifications, you will need to do a couple of things.

First steps

Unblu mobile SDK 3 requires Firebase 7. You must therefore first update your Podfile to:

pod 'Firebase/Core', '~> 7.0'
pod 'Firebase/Messaging'

Once you have done this, run pod update, or pod install if this is your first installation.

Next, add the UnbluFirebaseNotificationModule.xcframework to your project. As described above, simply drag the framework into your Xcode project.

The next steps depend on your whether or not you inherited from UnbluUiApplicationDelegate to integrate Firebase in your app.

Changes required if your `AppDelegate` inherited from `UnbluUiApplicationDelegate`

If your AppDelegate inherited from UnbluUiApplicationDelegate, you will now have to use UnbluFirebaseUIApplicationDelegate instead. The class is included in the UnbluFirebaseNotificationModule, so update your AppDelegate to look something like this:
import UnbluFirebaseNotificationModule //... class AppDelegate: UnbluFirebaseUIApplicationDelegate { //... }
If you defined var window: UIWindow? in your AppDelegate, you will need to remove this line and use the window property already defined in UnbluFirebaseUIApplicationDelegate.

To receive remote notification updates, override the 'on_application' methods of UnbluFirebaseUIApplicationDelegate related to receiving remote notifications. If you implemented the on_messaging function related to receiving remote messages with UnbluUiApplicationDelegate, you can remove it; it is no longer used.

Listing 1. Remote notification updates with Unblu mobile SDK 2

override func on_messaging(
    _ messaging: Messaging,
    didReceive remoteMessage: MessagingRemoteMessage)
{
    //...
}

Listing 2. Remote notification updates with Unblu mobile SDK 3

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any])
{
    //...
}

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
{
    //...
}

The on_messaging function related to receiving a device token has changed:

Listing 3. Receiving a device token with Unblu mobile SDK 2

override func on_messaging(
    _ messaging: Messaging,
    didReceiveRegistrationToken fcmToken: String)
{
    //...
}

Listing 4. Receiving a token with Unblu mobile SDK 3

override func on_messaging(
    didReceiveRegistrationToken fcmToken: String?)
{
    //...
}

Changes required if you integrated Firebase without `UnbluUiApplicationDelegate`

If you integrated Firebase without using UnbluUiApplicationDelegate, you now have two ways to proceed:

Use the new UnbluFirebaseNotificationCoordinator
Integrate Firebase manually

We will discuss each option in turn

`UnbluFirebaseNotificationCoordinator`

The easiest way to integrate Firebase in Unblu mobile SDK 3 is by using the new UnbluFirebaseNotificationCoordinator class. You can modify your current solution to look something like this:

Listing 5. Using the UnbluFirebaseNotificationCoordinator class introduced with Unblu mobile SDK 3

import UnbluFirebaseNotificationModule

//...

class AppDelegate: UIResponder, UIApplicationDelegate {

    private lazy var unbluFirebaseCoordinator = UnbluFirebaseNotificationCoordinator()

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
    {

        unbluFirebaseCoordinator.delegate = self (1)

        do {
            try unbluFirebaseCoordinator.handleInitialRemoteNotification(
                userInfo: launchOptions?[.remoteNotification] as? [AnyHashable: Any])
        } catch {
            (2)
        }

        return true
    }

    func application(
        _ application: UIApplication,
        didFailToRegisterForRemoteNotificationsWithError error: Error)
    {
        unbluFirebaseCoordinator.failedToRegisterForRemoteNotifications(error: error)
    }

    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable: Any])
    {

        do {
            try unbluFirebaseCoordinator.handleRemoteNotification(userInfo: userInfo)
        } catch {
            (2)
        }
    }

    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
    {

        do {
            try unbluFirebaseCoordinator.handleRemoteNotification(
                userInfo: userInfo,
                completionHandler: completionHandler)
        } catch {
            (2)
        }
    }
}

extension AppDelegate: UnbluFirebaseNotificationCoordinatorDelegate {

    func unbluFirebaseNotificationCoordinator(
        _ unbluFirebaseNotificationCoordinator: UnbluFirebaseNotificationCoordinator,
        didReceiveRegistrationToken token: String?)
    {
        //...
    }
}

1	Assign a delegate here to be notified of device token updates.
2	If an error is thrown, the notification was not intended for Unblu. Add your implementation here.

Integrating Firebase manually.

If you choose to manually integrate (like below), you will now have to request notification permissions yourself. Unblu mobile SDK 2 does this automatically. In Unblu mobile SDK 3, it is only done automatically if you use either UnbluFirebaseNotificationCoordinator or UnbluFirebaseUIApplicationDelegate.

Unblu mobile SDK 3 gives you more control over when to request notification permissions. See the code example below:

Listing 6. Manually requesting Firebase notification permissions in Unblu mobile SDK 3

import UnbluCoreSDK
import FirebaseCore
import FirebaseMessaging

//...

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        FirebaseApp.configure()
        Messaging.messaging().delegate = self

      	//...

      	UNUserNotificationCenter.current().requestAuthorization( (1)
              options: [.alert, .sound, .badge])
        {
            granted, error in
            DispatchQueue.main.async {
                if granted {
                    UIApplication.shared.registerForRemoteNotifications()
                }
            }
        }

      	//...

        return true
    }

    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable : Any],
        fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
    {

        do {
            try UnbluNotificationApi.instance.handleRemoteNotification(
                userInfo: userInfo,
                withCompletionHandler: completionHandler)
        } catch {
            (2)
        }
    }

    func application(
        _ application: UIApplication,
        didReceiveRemoteNotification userInfo: [AnyHashable : Any])
    {

        do {
            try UnbluNotificationApi.instance.handleRemoteNotification(userInfo: userInfo)
        } catch {
            (2)
        }
    }
}

extension AppDelegate: MessagingDelegate {

    func messaging(
        _ messaging: Messaging,
        didReceiveRegistrationToken fcmToken: String?)
    {
        UnbluNotificationApi.instance.deviceToken = fcmToken
    }
}

1	Request authorization to show notifications
2	If an error is thrown, the notification was not intended for Unblu.

Using UNUserNotificationCenterDelegate

If you want to use your own UNUserNotificationCenterDelegate and assign it to UNUserNotificationCenter.current().delegate, it is important that you do so in didFinishLaunchingWithOptions and to pass data to Unblu in the callbacks.

Make sure you do the following if you are assigning a value to UNUserNotificationCenter.current().delegate:

Listing 7. Using your own UNUserNotificationCenterDelegate with Unblu mobile SDK 3

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool
    {

        UNUserNotificationCenter.current().delegate = self (1)
        UnbluNotificationApi.instance.automaticHandlingEnabled = true

      	...

        return true
    }
}

extension AppDelegate: UNUserNotificationCenterDelegate { (2)

    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        didReceive response: UNNotificationResponse,
        withCompletionHandler completionHandler: @escaping () -> Void)
    {

        do {
            try UnbluNotificationApi.instance.didReceive(
                notificationResponse: response,
                withCompletionHandler: completionHandler)
        } catch {
            (3)
        }
    }

    func userNotificationCenter(
        _ center: UNUserNotificationCenter,
        willPresent notification: UNNotification,
        withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void)
    {

        do {
            try UnbluNotificationApi.instance.willPresent(
                notification: notification,
                withCompletionHandler: completionHandler)
        } catch {
            (3)
        }
    }
}

1	If the `UnbluNotificationApi` is configured to handle notifications automatically (it is disabled by default), it assigns `UNUserNotificationCenter.current().delegate` by itself. You can either deactivate the automatic handling or, if you still want to use it to handle clicked notifications, you can set your own delegate before. This delegate will not be overwritten. If you want to use your own delegate, e.g. by setting `UNUserNotificationCenter.current().delegate = self`, see the example implementation of the delegate in the extension.
2	It is essential that you pass data to Unblu in the callbacks here
3	If an error is thrown, the notification was not intended for Unblu.

Changes to `UnbluApiConfiguration`

The way the UnbluApiConfiguration is created has changed. In Unblu mobile SDK 2, initialization looked like this:

Listing 8. Initializing UnbluApiConfiguration with Unblu mobile SDK 2

let configuration = UnbluApiConfiguration(unbluBaseUrl: "", apiKey: "")

With Unblu mobile SDK 3, you now have to specify

the storage location of your preferences, and
the file download handler you would like to use.

These are specified with two new arguments.

Listing 9. Initializing UnbluApiConfiguration with Unblu mobile SDK 2

var configuration = UnbluApiConfiguration(
                        unbluBaseUrl: "",
                        apiKey: "",
                        preferencesStorage: ...,
                        fileDownloadHandler: ...
                    )

`preferencesStorage: UnbluPreferencesStorage`

Unblu mobile SDK 3 provides two preferences storage classes:

You should not need to use UnbluKeychainPreferencesStorage. For more information on these classes, please refer to the documentation.

If you did not provide your own preferences storage implementation with Unblu mobile SDK 2, pass in an instance of UserDefaultsPreferencesStorage when you initialize UnbluApiConfiguration:

Listing 10. Initializing UnbluApiConfiguration without custom preferences storage implementation with Unblu mobile SDK 3

var config = UnbluApiConfiguration(
  				unbluBaseUrl: "",
  				apiKey: "",
  				preferencesStorage: UserDefaultsPreferencesStorage(),
  				fileDownloadHandler: ...
			)

If you did provide your own preferences storage implementation with Unblu mobile SDK 2, pass it in when you initialize UnbluApiConfiguration. This is what initialization looks like with Unblu mobile SDK 2:

Listing 11. Initializing UnbluApiConfiguration with custom preferences storage implementation with Unblu mobile SDK 2

let customPreferencesStorage = ...

UnbluApiConfiguration(unbluBaseUrl: "", apiKey: "")
	.setPreferencesStorage(preferencesStorage: customPreferencesStorage)

With Unblu mobile SDK 3, it looks like this:

Listing 12. Initializing UnbluApiConfiguration with custom preferences storage implementation with Unblu mobile SDK 3

let customPreferencesStorage = ...

var config = UnbluApiConfiguration(
  				unbluBaseUrl: "",
  				apiKey: "",
  				preferencesStorage: customPreferencesStorage,
  				fileDownloadHandler: ...
			)

`fileDownloadHandler: UnbluFileDownloadHandler`

In Unblu mobile SDK 3, you must specify a file download handler. Unblu provides one for you called UnbluDefaultFileDownloadHandler, and you should pass an instance of this when you initialize UnbluApiConfiguration:

Listing 13. Passing an instance of UnbluDefaultFileDownloadHandler when initializing UnbluApiConfiguration with Unblu mobile SDK 3

var config = UnbluApiConfiguration(
                unbluBaseUrl: "",
                apiKey: "",
                preferencesStorage: ...,
                fileDownloadHandler: UnbluDefaultFileDownloadHandler()
            )

`customCookies`

customCookies is now a Set of UnbluCookie objects and no longer a Dictionary of String key-value pairs. It is also now set via a property on the configuration object rather than via a function. So with Unblu mobile SDK 2, you set customCookies as follows:

Listing 14. Setting customCookies with Unblu mobile SDK 2

let customCookies = ["cookieName": "cookieValue"]

UnbluApiConfiguration(unbluBaseUrl: "", apiKey: "")
	.setCustomCookies(customCookies)

With Unblu mobile SDK 3, setting customCookies looks like this:

Listing 15. Setting customCookies with Unblu mobile SDK 3

let customCookies = [
	UnbluCookie(name: "cookieName", value: "cookieValue")
]

var config = UnbluApiConfiguration(...)
config.customCookies = Set(customCookies)

UnbluCookie objects can be created either by passing a name and values directly, or by passing an instance of the HTTPCookie class that is part of the Swift standard library:

Listing 16. Creating UnbluCookie objects with Unblu mobile SDK 3

// Examples of creating an UnbluCookie by passing specific arguments
UnbluCookie(name: "cookieName", value: "123"),
UnbluCookie(name: "cookie2Name", value: "456", expiryDate: Date()),

// Examples of creating an UnbluCookie using HTTPCookie
UnbluCookie(httpCookie: HTTPCookie(properties: [.name: "httpCookie1", .value: "value", .path: "/", .domain: "example.com"])!),
UnbluCookie(httpCookie: HTTPCookie(properties: [.name: "httpCookie2", .value: "value", .path: "/", .domain: "example.com", .expires: Date()])!),
UnbluCookie(httpCookie: HTTPCookie(properties: [.name: "httpCookie3", .value: "value", .path: "/", .domain: "example.com", .maximumAge: 180])!)

Properties are no longer set via functions

As with the customCookies property above, properties that were previously set via functions are now set via dot notation, i.e. .<property name>. The Swift compiler will highlight these for you when you migrate, but here are some examples of the property setters that have changed:

Unblu mobile SDK 2 Unblu mobile SDK 3

Unblu mobile SDK 2	Unblu mobile SDK 3
`setPreloadUiAfterApiInitEnabled(…)`	`preloadUiAfterApiInitEnabled`` = …`
`setAuthenticationChallengeDelegate(…)`	`authenticationChallengeDelegate`` = …`
`setInternalUrlPatternWhitelist(…)`	`internalUrlPatternWhitelist`` = …`
`setExternalLinkPatternWhitelist(…)`	`externalLinkPatternWhitelist`` - …`
`setLanguage(…)`	`language`` = …`
`setNamedArea(…)`	`namedArea`` = …`
`setNotificationsEnabled(…)`	`UnbluNotificationApi.automaticHandlingEnabled`` = …`
`setEntryPath(…)`	`entryPath`` = …`

setPreloadUiAfterApiInitEnabled(…)

preloadUiAfterApiInitEnabled` = …`

setAuthenticationChallengeDelegate(…)

authenticationChallengeDelegate` = …`

setInternalUrlPatternWhitelist(…)

internalUrlPatternWhitelist` = …`

setExternalLinkPatternWhitelist(…)

externalLinkPatternWhitelist` - …`

setLanguage(…)

language` = …`

setNamedArea(…)

namedArea` = …`

setNotificationsEnabled(…)

UnbluNotificationApi.automaticHandlingEnabled` = …`

setEntryPath(…)

entryPath` = …`

Modules must be registered

In Unblu mobile SDK 2, UnbluCoreSDK contained code for various optional features. As a result it was always launched — even if it was not needed.

In Unblu mobile SDK 3, this code is now in separate modules. If you want to use these modules, you have to register them with the UnbluApiConfiguration object before you initialize the latter. Make sure to do so by adding the following code wherever you create UnbluApiConfiguration:

Listing 17. Registering individual Unblu modules

import UnbluCallModule
import UnbluCoBrowsingModule

//...

var config: UnbluApiConfiguration = ... (1)

// register the modules
config.register(modules: [UnbluCallModuleProvider.module,
                          UnbluCoBrowsingModuleProvider.module])

1	Replace `…` with the appropriate code for your use case.

Changes to `AuthenticationChallengeDelegate`

In Unblu mobile SDK 3, there is now only one function in the AuthenticationChallengeDelegate protocol. You should handle all authentication challenges in this one function.

In Unblu mobile SDK 2, your challenge handler might have looked like this:

Listing 18. AuthenticationChallengeDelegate protocol in Unblu mobile SDK 2

class CustomChallengeHandler: AuthenticationChallengeDelegate {

    func webView(
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void)
    {
        //...
    }

    func fileDownload(
        didReceive challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void)
    {
        //...
    }
}

With Unblu mobile SDK 3, it should instead look something like this:

Listing 19. AuthenticationChallengeDelegate protocol in Unblu mobile SDK 3

class CustomChallengeHandler: AuthenticationChallengeDelegate {

    func didReceive(
        authenticationChallenge challenge: URLAuthenticationChallenge,
        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void)
    {
        //...
    }
}

Changes to the co-browsing API

All actions and events related to co-browsing are now in the module UnbluCoBrowsingModule. In Unblu mobile SDK 2, such actions and events were accessed via UnbluVisitorApi.instance; now you access them via UnbluCoBrowsingModuleProvider.api.

Listing 20. addPrivateView

/*
    version 2
*/
UnbluVisitorApi.instance.addPrivateView(withTag: ...)

/*
    version 3
*/
import UnbluCoBrowsingModule

//...

UnbluCoBrowsingModuleProvider.api.addPrivateView(withTag: ...)

Listing 21. removePrivateView

/*
    version 2
*/
UnbluVisitorApi.instance.removePrivateView(withTag: ...)

/*
    version 3
*/
import UnbluCoBrowsingModule

//...

UnbluCoBrowsingModuleProvider.api.removePrivateView(withTag: ...)

Listing 22. isMobileCoBrowsingActive

/*
    version 2
*/
UnbluVisitorApi.instance.isMobileCoBrowsingActive { isActive in

} failure: { error in

}

/*
    version 3
*/
import UnbluCoBrowsingModule

//...

UnbluCoBrowsingModuleProvider.api.isMobileCoBrowsingActive { isActive in

} failure: { error in

}

Listing 23. stopMobileCoBrowsing

/*
    version 2
*/
UnbluVisitorApi.instance.stopMobileCoBrowsing {

} failure: { error in

}

/*
    version 3
*/
import UnbluCoBrowsingModule

//...

UnbluCoBrowsingModuleProvider.api.stopMobileCoBrowsing {

} failure: { error in

}

Changes to the call API

Like those of the co-browsing API, all actions and events related to calls are now included in a separate module, UnbluCallModule. In Unblu mobile SDK 2, such actions and events were accessed via UnbluVisitorApi.instance; now you access them via UnbluCallModuleProvider.api.

Listing 24. isCallActive

/*
    version 2
*/
UnbluVisitorApi.instance.isCallActive { isActive in

}

/*
    version 3
*/
import UnbluCallModule

//...

UnbluCallModuleProvider.api.isCallActive { isActive in

}

Changes to the Unblu event API

The events fired by the mobile co-browsing and call modules have been moved from the UnbluEventApi to two new classes, UnbluCoBrowsingEventApi and UnbluCallEventApi, respectively:

Listing 25. MobileCoBrowsingChanged

/*
    version 2
*/
UnbluEventApi.MobileCoBrowsingChanged.<property name>

/*
    version 3
*/
import UnbluCoBrowsingModule

//...

UnbluCoBrowsingEventApi.MobileCoBrowsingChanged.<property name>

Listing 26. CallActiveChanged

/*
    version 2
*/
UnbluEventApi.CallActiveChanged.<property name>

/*
    version 3
*/
import UnbluCallModule

//...

UnbluCallEventApi.CallActiveChanged.<property name>

Migrating to version 3 of the Android mobile SDK

The minimum version of the Android OS supported by Unblu is Android 6.0. If your project use a version of Android below 6.0, you will need to update your project to a minimum API level of 23 (android:minSdkVersion="23") or Unblu will not run.

Installation

Installing the SDK is easy. Simply add the dependencies — the SDK itself and any optional modules you require — to your application’s build.gradle file. Note that in the example below, the version 3.x.x is not valid. You should provide the specific build version you need.

Listing 27. 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.2.0'
    implementation 'com.google.android.material:material:1.2.0'

    // Unblu-related dependencies; replace 3.x.x with the concrete version
    // you want to use, e.g. 3.3.1
    implementation 'com.unblu.mobile-sdk-android:visitorsdk:3.x.x'
    implementation 'com.unblu.mobile-sdk-android:callmodule:3.x.x'
    implementation 'com.unblu.mobile-sdk-android:cobrowsingmodule:3.x.x'
    implementation 'com.unblu.mobile-sdk-android:firebasenotificationmodule:3.x.x'
    implementation 'com.unblu.mobile-sdk-android:advancedscreencapturemodule:3.x.x'
}

Firebase and `UnbluNotificationApi`

To continue using Firebase for push notifications with the Unblu mobile SDK 3, import com.unblu.mobile-sdk-android:firebasenotificationmodule in your build.gradle. Then add our service or an extension of it to your manifest:

Listing 28. Manifest excerpt to use Firebase with Unblu mobile SDK 3

<service
  android:name="com.unblu.sdk.module.firebase_notification.UnbluFirebaseNotificationService"
  android:exported="false">
  <intent-filter>
    <action android:name="com.google.firebase.MESSAGING_EVENT" />
  </intent-filter>
</service>

If you prefer to implement your own push notifications, you can still use the IUnbluNotificationApi to display notifications related to Unblu:

Listing 29. Using the UnbluNotificationApi with Unblu mobile SDK 3

RemoteNotification remoteNotification =
    new RemoteNotification(
        title,
        body,
        RemoteNotificationHelper.getNotificationIcon(context),
        sound,
        channelId,
        data
    );

UnbluCoreApi.getNotificationApi().onMessageReceived(remoteNotification, context);

Note that the approach in the example above makes no use of the Unblu firebasenotificationmodule. It also does not require you to register the UnbluFirebaseNotificationService.

`UnbluApiConfiguration`

In version 3 of the mobile SDK, the UnbluAgentApiConfiguration and UnbluVisitorApiConfiguration classes have been replaced by a single class, UnbluApiConfiguration. When you initialize UnbluApiConfiguration, you must provide two additional pieces of information:

The location where preferences should be stored
The file download handler you would like to use; in version 2, this was the ExterrnalStorageDownloadListener

With Unblu mobile SDK 2, initializing the configuration may have looked like this:

Listing 30. Initializing UnbluVisitorApiConfiguration with Unblu mobile SDk 2

new UnbluVisitorApiConfiguration(getBaseUrl(), getApiKey())
    .setCustomCookies(customCookies)
    .setPreloadUiAfterApiInitEnabled(true);

With version 3, it would look like this:

Listing 31. Initializing UnbluApiConfiguration with Unblu mobile SDk 3

new UnbluApiConfiguration.Builder(
    "http://www.example.com/?val=argument",
    "MkLVcqFVfB",
    UnbluPreferencesStorage.createSharedPreferencesStorage(context()),
    UnbluDownloadHandler.createExternalStorageDownloadHandler(context())
).build();

`UnbluApiConfiguration` builder

UnbluApiConfiguration is not mutable. Instead, we provide a Builder pattern.

The following setter methods from version 2 of the mobile SDK are not available or have been renamed in the new UnbluApiConfiguration.Builder in version 3:

Listing 32. Changed setter methods from version 2

setDownloadListener(); // --> replaced by setDownloadHandler()
setLoginInformation(); // --> dropped

`SharedPreferencesStorage`

Unblu provides a default preferences storage solution using EncryptedSharedPreferences which you can use out of the box.

Listing 33. Using EncryptedStoragePreferences with mobile SDK 3

new UnbluApiConfiguration.Builder(
    "http://www.example.com/?val=argument",
    "MkLVcqFVfB",
    UnbluPreferencesStorage.createSharedPreferencesStorage(context()),
    UnbluDownloadHandler.createExternalStorageDownloadHandler(context())
).build();

Alternatively, you can provide a custom preferences storage implementation. To do so, extend UnbluPreferencesStorage and pass an instance of your custom preferences storage when you initialize UnbluApiConfiguration.

Listing 34. Using a custom preferences storage with mobile SDK 3

CustomPreferencesStorage customPreferencesStorage = ... (1)

new UnbluApiConfiguration.Builder(
    "http://www.example.com/?val=argument",
    "MkLVcqFVfB",
    customPreferencesStorage,
    UnbluDownloadHandler.createExternalStorageDownloadHandler(context())
).build();

1	Amend with your preferences storage implementation.

`UnbluDownloadHandler`

In Unblu mobile SDK 3, you must explicitly specify a file download handler. Unblu provides one via UnbluDownloadHandler.createExternalStorageDownloadHandler(). You can pass an instance of it when you initialize UnbluApiConfiguration:

Listing 35. Passing the built-in file download handler to UnbluApiConfiguration with mobile SDK 3

ExternalStorageDownloadHandler downloadHandler =
    UnbluDownloadHandler.createExternalStorageDownloadHandler(context());

UnbluApiConfiguration configuration =
    new UnbluApiConfiguration.Builder(
        "http://www.example.com/?val=argument",
        "MkLVcqFVfB",
        UnbluPreferencesStorage.createSharedPreferencesStorage(context()),
        downloadHandler)
    ).build();

Alternatively, you can provide your own implementation by extending UnbluDownloadHandler.

Listing 36. Passing a custom file download handler to UnbluApiConfiguration with mobile SDK 3

CustomDownloadHandler customDownloadHandler = ... (1)

new UnbluApiConfiguration.Builder(
                "http://www.example.com/?val=argument",
                "MkLVcqFVfB",
                UnbluPreferencesStorage.createSharedPreferencesStorage(context()),
                customDownloadHandler)
        ).build();

1	Amend with your file download handler implementation.

`customCookies`

In Unblu mobile SDK 3, customCookies is no longer a Map of String key-value pairs set with a function:

Listing 37. Setting customCookies in Unblu mobile SDK version 2

final Map<String, String> customCookies - new HashMap<>();
customCookies,put("Cookie1", "cookieValue1");

unbluApi.setCustomCookies(customCookies);

Instead, it is a Set of UnbluCookie objects set via a property on the configuration. UnbluCookie objects can be created by passing values directly, or by passing a java.net.HttpCookie object, which is part of the standard library:

Listing 38. Setting customCookies in Unblu mobile SDK 3

final Map<String, String> customCookiesMap = new HashMap<>();
customCookiesMap.put("Cookie1", "cookieValue1");
customCookiesMap.put("Cookie2", "cookieValue2");

Set<UnbluCookie> unbluCookies = UnbluCookie.from(customCookiesMap);

unbluApiConfigurationBuilder.setCustomCookies(unbluCookies);

Listing 39. Creating UnbluCookie objects and setting customCookies in Unblu mobile SDK 3

final List<UnbluCookie> customCookiesList = new Vector<>();

// Create an UnbluCookie from an HttpCookie and add it to customCookiesList
customCookiesList.addElement(
    new UnbluCookie(new HttpCookie("Cookie1", "cookievalue1"))
);

// Create an UnbluCookie by passing values directly
customCookiesList.addElement(
    new UnbluCookie("Cookie2", "cookieValue2")
);

// Create an UnbluCookie with an expiry date by passing values directly
customCookiesList.addElement(
    new UnbluCookie("Cookie3", "cookieValue3", )
);

Set<UnbluCookie> customCookies = UnbluCookie.from(customCookiesList);

unbluApiConfigurationBuilder.setCustomCookies(unbluCookies);

Modules must be registered

In Unblu mobile SDK 2, UnbluCoreSDK contained code for various optional features. As a results it was always launched, even if it was not needed.

In Unblu mobile SDK 3, this code is now in separate modules. If you want to use these modules, you will need to register them with the UnbluApiConfiguration.Builder object before initializing:

Listing 40. Registering modules with UnbluApiConfiguration.Builder

return new UnbluApiConfiguration.Builder(
    getBaseUrl(),
    getApiKey(),
    UnbluPreferencesStorage.createSharedPreferencesStorage(
        getApplicationContext()
    ),
    UnbluDownloadHandler.createExternalStorageDownloadHandler(
        getApplicationContext()
    )
)
    .registerModule(UnbluCallModule.getModule())
    .registerModule(UnbluCoBrowsingModule.getModule())
    .build();

Please refer to the Android mobile SDK documentation for more detailed information.

Changes to the co-browsing API

In Unblu mobile SDK 3, all actions and events related to co-browsing are now in a new module, UnbluCoBrowsingModule. In Unblu mobile SDK 2, such actions and events were accessed via UnbluVisitorApi.getInstance(); now you should access them using UnbluCoBrowsingModule.getApi().

Listing 41. addPrivateView

/*
    version 2
*/
UnbluVisitorApi.getInstance().addPrivateView(...)

/*
    version 3
*/
import com.unblu.sdk.module.cobrowsing.UnbluCoBrowsingModule;

//...
UnbluCoBrowsingModule.getApi().addPrivateView(...)

Listing 42. removePrivateView

/*
    version 2
*/
UnbluVisitorApi.getInstance().removePrivateView(...)

/*
    version 3
*/
import com.unblu.sdk.module.cobrowsing.UnbluCoBrowsingModule;

//...
UnbluCoBrowsingModule.getApi().removePrivateView()

Listing 43. isMobileCoBrowsingActive

/*
    version 2
*/
boolean isMobileCoBrowsingActive = UnbluVisitorApi.getInstance().isMobileCoBrowsingActive();

/*
    version 3
*/
import com.unblu.sdk.module.cobrowsing.UnbluCoBrowsingModule;

//...
boolean isMobileCoBrowsingActive = UnbluCoBrowsingModule.getApi().isMobileCoBrowingActive();

Listing 44. stopMobileCoBrowsing

/*
    version 2
*/
UnbluVisitorApi.getInstance().stopMobileCoBrowsing(
    value -> Log.d(
        TAG,
        "successfully stopped mobile co-browsing"
    ),
    new IUnbluApiStopMobileCoBrowsingExceptionCallback() {
        @Override
        public void onStopFailed(
            @NonNull UnbluStopMobileCoBrowsingErrorType type,
            @Nullable String details
        ) {
            //...
        }

        @Override
        public void onUiWasNeverShown() {
            //...
        }

        @Override
        public void onNotInitialized() {
            //...
        }
    }
);

/*
    version 3
*/
import com.unblu.sdk.module.cobrowsing.UnbluCoBrowsingModule;

//...

UnbluCoBrowsingModule.getApi().stopMobileCoBrowsing(
    value -> Log.d(
        TAG,
        "successfully stopped mobile co-browsing"
    ),
    new IUnbluApiStopMobileCoBrowsingExceptionCallback() {
        @Override
        public void onStopFailed(
            @NonNull UnbluStopMobileCoBrowsingErrorType type,
            @Nullable String details
        ) {
            //...
        }

        @Override
        public void onUiWasNeverShown() {
            //...
        }

        @Override
        public void onNotInitialized() {
            //...
        }
    }
);

Changes to the call API

As with the actions and events of the co-browsing API, those of the call API have been moved to a new module, UnbluCallModule. You should replace calls accessing the API using UnbluVisitorApi.getInstance() with calls to UnbluCallModule.getApi().

Listing 45. isCallActive()

/*
    version 2
*/
UnbluVisitorApi.getInstance().isCallActive();

/*
    version 3
*/
import com.unblu.sdk.module.call.UnbluCallModule;

//...

boolean isCallActive = UnbluCallModule.getApi().isCallActive();

Changes to the Unblu event API

The events fired by the mobile co-browsing and call modules have been moved from the UnbluVisitorEventReceiver to two new classes, UnbluCoBrowsingEventReceiver and UnbluCallEventReceiver, respectively:

Listing 46. MobileCoBrowsingChanged

/*
    version 2
*/
UnbluVisitorEventReceiver unbluBroadcastReceiver =
    new UnbluVisitorEventReceiver(getApplicationContext()) {

        //...

        @Override
        protected void onMobileCoBrowsingChanged(final boolean active) {
            //...
        }
    };

/*
    version 3
*/
import com.unblu.sdk.module.cobrowsing.UnbluCoBrowsingEventReceiver;

...

UnbluCoBrowsingEventReceiver unbluCoBrowsingBroadcastReceiver =
    new UnbluCoBrowsingEventReceiver(getApplicationContext()) {

        //...

        @Override
        protected void onMobileCoBrowsingChanged(final boolean active) {
            //...
        }
    };

Listing 47. CallActiveChanged

/*
    version 2
*/
UnbluVisitorEventReceiver unbluBroadcastReceiver =
    new UnbluVisitorEventReceiver(getApplicationContext()) {

        //...

        @Override
        protected void onCallActiveChanged(final boolean active) {
            //...
        }
    };

/*
    version 3
*/
import com.unblu.sdk.module.call.UnbluCallEventReceiver;

//...

UnbluCallEventReceiver unbluCallBroadcastReceiver =
    new UnbluCallEventReceiver(getApplicationContext()) {

        //...

        @Override
        protected void onCallActiveChanged(final boolean active) {
            //...
        }
    };

Unblu mobile SDK: migrating from version 2 to version 3

Migrating to version 3 of the iOS mobile SDK

Installation

Firebase

First steps

Changes required if your AppDelegate inherited from UnbluUiApplicationDelegate

Changes required if you integrated Firebase without UnbluUiApplicationDelegate

UnbluFirebaseNotificationCoordinator

Integrating Firebase manually.

Using UNUserNotificationCenterDelegate

Changes to UnbluApiConfiguration

preferencesStorage: UnbluPreferencesStorage

fileDownloadHandler: UnbluFileDownloadHandler

customCookies

Properties are no longer set via functions

Modules must be registered

Changes to AuthenticationChallengeDelegate

Changes to the co-browsing API

Changes to the call API

Changes to the Unblu event API

Migrating to version 3 of the Android mobile SDK

Installation

Firebase and UnbluNotificationApi

UnbluApiConfiguration

UnbluApiConfiguration builder

SharedPreferencesStorage

UnbluDownloadHandler

customCookies

Modules must be registered

Changes to the co-browsing API

Changes to the call API

Changes to the Unblu event API

Changes required if your `AppDelegate` inherited from `UnbluUiApplicationDelegate`

Changes required if you integrated Firebase without `UnbluUiApplicationDelegate`

`UnbluFirebaseNotificationCoordinator`

Changes to `UnbluApiConfiguration`

`preferencesStorage: UnbluPreferencesStorage`

`fileDownloadHandler: UnbluFileDownloadHandler`

`customCookies`

Changes to `AuthenticationChallengeDelegate`

Firebase and `UnbluNotificationApi`

`UnbluApiConfiguration`

`UnbluApiConfiguration` builder

`SharedPreferencesStorage`

`UnbluDownloadHandler`

`customCookies`