Unblu iOS 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 iOS. For Android, refer to Unblu Android mobile SDK: migrating from version 3 to version 4.
Requirements
The minimum supported iOS version for the Unblu iOS mobile SDK version 4 is iOS 13. If your project uses an iOS version below this, you will need to update your project to iOS version 13.0 or newer. The Unblu iOS mobile SDK will not be able to run otherwise.
The minimum supported Unblu Collaboration Server version is 7.x.x.
Installation
In version 3 of the iOS SDK, there were individual frameworks for visitor and agent functionality. In version 4, this is no longer the case. Instead, the functionality of these frameworks is bundled in the UnbluCoreSDK
framework. You must therefore remove any imports of the frameworks that are no longer available.
We also recommend that you clean your Xcode project after this to make sure references are updated.
To install the Unblu iOS mobile SDK, drag the XCFramework
s you require into your Xcode project, then add them to your target. The available XCFramework
s are
-
UnbluCallModule.xcframework
-
UnbluMobileCoBrowsingModule.xcframework
-
UnbluCoreSDK.xcframework
-
UnbluFirebaseNotificationModule.xcframework
-
UnbluVisitorSDK.xcframework
When copying the XCFramework
s into your project, make sure to check the box Copy items if needed.
Initializing Unblu
The way Unblu is initialized and configured has changed in version 4.
-
The Unblu instance is no longer accessible via a singleton
.instance
property. Instead, you must create the Unblu instance and manage its lifecycle yourself. -
The configuration object needed to initialize the Unblu instance is now called
UnbluClientConfiguration
. See below for further details.
Initializing Unblu therefore looks like the following code snippets:
// Version 3
let visitorConfig = UnbluApiConfiguration(...)
try? UnbluVisitorApi.instance.configureApi(configuration: visitorConfig)
UnbluVisitorApi.instance.<property_name>
let agentConfig = UnbluApiConfiguration(...)
try? UnbluAgentApi.instance.configureApi(configuration: agentConfig)
UnbluAgentApi.instance.<property_name>
// Version 4
let visitorConfig = UnbluClientConfiguration(...)
let unbluVisitor = Unblu.createVisitorClient(withConfiguration: visitorConfig)
unbluVisitor.<property_name>
let agentConfig = UnbluClientConfiguration(...)
let unbluAgent = Unblu.createAgentClient(withConfiguration: agentConfig)
unbluAgent.<property_name>
initApi()
and deinitApi()
are now called start
and stop
respectively.
// Version 3
UnbluVisitorApi.instance.initApi(success: {
}) { (error) in
}
UnbluVisitorApi.instance.deinitApi()
// Version 4
unbluVisitor.start { result in
// process the result
}
unbluVisitor.stop { result in
// process the result
}
Configuring Unblu
As mentioned above, UnbluApiConfiguration
is now called UnbluClientConfiguration
.
The properties of the new object are largely the same as those of UnbluApiConfiguration
, except with regard to the handling of external links.
The externalLinkPatternWhitelist
property is no longer available on the configuration object. It has been superseded by the externalLinkHandler
property and the new UnbluExternalLinkHandler
protocol.
When you initialize UnbluClientConfiguration
, you must provide an object that conforms to the UnbluExternalLinkHandler
protocol. Unblu provides a default implementation of this protocol called UnbluDefaultExternalLinkHandler
.
When a link is tapped in a conversation, Unblu calls the function decidePolicy(for: URL) → UnbluExternalLinkHandlingPolicy
on the UnbluExternalLinkHandler
. How Unblu proceeds depends on whether the function returns .open
, .block
, or .ignore
.
UnbluClientConfiguration
exposes the link handler via the new externalLinkHandler
property.
For more information, please review the Unblu iOS mobile SDK reference entries of the following types:
UnbluView
In version 3 of the Unblu mobile SDK all Unblu UI content was rendered in a UIWindow
that was managed internally by Unblu. To show the Unblu UI, you had to call showUi(true/false)
explicitly.
Now, Unblu provides you with a subclass of UIView
called UnbluView
. The entire Unblu UI is rendered into this view.
Providing a UIView
makes integrating Unblu into your application simpler and enables a greater degree of control over where the Unblu UI is displayed in your app.
The UnbluView
is available as a view
property on the Unblu client instance. A typical approach is to add the UnbluView
to a UIViewController
when viewDidLoad
is called:
class MyViewController: UIViewController {
var unbluVisitor: UnbluVisitorClient!
override func viewDidLoad() {
super.viewDidLoad()
view.addSubview(unbluVisitor.view)
}
}
How you position the UnbluView
within your app is entirely up to you. It supports autolayout constraints and/or setting the .frame
property.
Show and hiding the Unblu UI
Because there is no longer a call to showUi(true/false)
, Unblu no longer knows for sure when it is visible in your app. It is important that Unblu knows this information in order to correctly display notifications.
The UnbluView
itself tries to work out whether it is visible or not by reading its UIView.isHidden
property. In some circumstances, however, this won’t be sufficient. For example, you might have another UIView
on top of the UnbluView
, thereby obscuring it from view.
In such a situation, we ask that you try as best you can to keep Unblu informed when the UnbluView
is visible. There are two functions in the UnbluView
that facilitate this:
In most circumstances it won’t be necessary to use these functions, but you should bear them in mind when integrating the UnbluView
.
New type for conversations
In version 4 of the mobile SDK, there’s a new type, UnbluConversation
, that represents a specific conversation. You can now always retrieve the current open conversation via the UnbluClient.openConversation
property.
Additionally, when a conversation is opened or closed, Unblu calls the delegate
function unblu(didChangeOpenConversation:)
.
Unblu events
Version 4 of the iOS mobile SDK no longer uses the NotificationCenter
to dispatch events. Instead, events are dispatched using delegates that you can adopt and assign to your Unblu
instance.
Contrast the following examples from version 3 and version 4:
// Version 3
NotificationCenter.default.addObserver(self, selector: #selector(...), name: .UnbluUiVisibilityRequest, object: UnbluVisitorApi.instance)
// Version 4
let unbluVisitor = Unblu.createVisitorClient(...)
unbluVisitor.visitorDelegate = <assign-your-delegate> (1)
class ExampleDelegate: UnbluVisitorClientDelegate {
func unblu(didRequestShowUi reason: UnbluUiRequestReason, requestedByUser: Bool) {
}
}
1 | Replace <assign-your-delegate> with the delegate |
Below is a list of the Notification types in version 3 and the functions provided by the delegate protocols in version 4 that replace them. For information on additional delegate protocols you can adopt, please refer to the iOS SDK reference documentation.
-
Notification.Name.UnbluApiIsInitialized
class ExampleDelegate: UnbluVisitorClientDelegate { func unbluDidInitialize() { //... } func unbluDidDeinitialize() { //... } }
-
Notification.Name.UnbluUiReady
class ExampleDelegate: UnbluVisitorClientDelegate { func unbluUiIsReady() { //... } }
-
Notification.Name.UnbluUiPreloaded
class ExampleDelegate: UnbluVisitorClientDelegate { func unbluDidPreloadUi() { //... } }
-
Notification.Name.UnbluUnreadMessagesCountChanged
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didUpdateUnreadMessages count: Int) { //... } }
-
Notification.Name.UnbluPersonChanged
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didUpdatePersonInfo personInfo: PersonInfo) { //... } }
-
Notification.Name.UnbluError
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didReceiveError type: UnbluApiErrorType, description: String) { //... } }
-
Notification.Name.UnbluUiVisibilityTransition
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didTransitionUiWithTransition transition: UnbluUiVisibilityTransition) { //... } }
-
Notification.Name.UnbluUiOpenConversationChanged
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didChangeOpenConversation openConversation: UnbluConversation?) { //... } }
-
Notification.Name.UnbluUiVisibilityRequest
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didRequestShowUi reason: UnbluUiRequestReason, requestedByUser: Bool) { //... } }
-
Notification.Name.UnbluUiHideRequest
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didRequestHideUi reason: UnbluUiHideRequestReason, conversationId: String?) { //... } }
-
Notification.Name.UnbluUiCallUiOpenChanged
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didToggleCallUi isOpen: Bool) { //... } }
-
Notification.Name.UnbluAgentAvailable
class ExampleDelegate: UnbluVisitorClientDelegate { func unblu(didUpdateAgentAvailability isAvailable: Bool) { //... } }
-
Notification.Name.UnbluMobileCoBrowsingChanged
class ExampleDelegate: UnbluMobileCoBrowsingModuleDelegate { func unbluMobileCoBrowsingModuleDidStartCoBrowsing(_ unbluMobileCoBrowsingModuleApi: UnbluMobileCoBrowsingModuleApi) { //... } func unbluMobileCoBrowsingModuleDidStopCoBrowsing(_ unbluMobileCoBrowsingModuleApi: UnbluMobileCoBrowsingModuleApi) { //... } }
-
Notification.Name.UnbluCallActiveChanged
class ExampleDelegate: UnbluCallModuleDelegate {
func unbluCallModuleDidStartCall(_ unbluCallModuleApi: UnbluCallModuleApi) {
//...
}
func unbluCallModuleDidEndCall(_ unbluCallModuleApi: UnbluCallModuleApi) {
//...
}
}
Changes to UnbluCoBrowsingModule
The UnbluCoBrowsingModule
is now called UnbluMobileCoBrowsingModule
. This change makes it more explicit which co-browsing layer the module manipulates, namely the mobile co-browsing layer.
There have been a number of other changes to the UnbluMobileCoBrowsingModule
. We have added a number of APIs to UnbluMobileCoBrowsingModuleApi
: * addPrivateArea(withId:x:y:width:height)
* removePrivateArea(withId:)
* maxWindowCapturingLevel
* preferredStatusBarStyle
The module also has a new delegate, UnbluMobileCoBrowsingModuleDelegate
, and a new struct for configuring the module, UnbluMobileCoBrowsingModuleConfiguration
. Please refer to the iOS mobile SDK reference documentation for more details.
The UnbluMobileCoBrowsingModuleProvider
doesn’t have api
instance you can use like the UnbluCoBrowsingModuleProvider
in version 3 did. This affects several existing APIs:
-
To use the API of the
UnbluMobileCoBrowsingModule
,UnbluMobileCoBrowsingModuleProvider
now provides acreate(config:)
function:// Version 3 let coBrowsingModule = UnbluCoBrowsingModuleProvider.module // Version 4 let mobileCoBrowsingModuleConfig = UnbluMobileCoBrowsingModuleConfiguration(...) let mobileCoBrowsingModule = UnbluMobileCoBrowsingModuleProvider.create(config: mobileCoBrowsingModuleConfig)
-
Because of the lack of an
api
instance inUnbluMobileCoBrowsingModuleProvider
, the following tasks are also different in version 4:-
Adding and removing private views:
// Version 3 import UnbluCoBrowsingModule //... UnbluCoBrowsingModuleProvider.api.addPrivateView(withTag: ...) //... UnbluCoBrowsingModuleProvider.api.removePrivateView(withTag: ...) // Version 4 let mobileCoBrowsingModule: UnbluMobileCoBrowsingModuleApi mobileCoBrowsingModule.addPrivateView(withTag: ...) //... mobileCoBrowsingModule.removePrivateView(withTag: ...)
-
Checking for active mobile co-browsing sessions:
// Version 3 import UnbluCoBrowsingModule //... UnbluCoBrowsingModuleProvider.api.isMobileCoBrowsingActive { isActive in //... } failure: { error in //... } // Version 4 let mobileCoBrowsingModule: UnbluMobileCoBrowsingModuleApi mobileCoBrowsingModule.isMobileCoBrowsingActive { isActive in //... } failure: { error in //... } // You can also check for an active mobile co-browsing session via a conversation let conversation: UnbluConversation let isMobileCoBrowsingActive = conversation.isMobileCoBrowsingActive
-
Stopping active mobile co-browsing sessions:
// Version 3 import UnbluCoBrowsingModule //... UnbluCoBrowsingModuleProvider.api.stopMobileCoBrowsing { //... } failure: { error in //... } // Version 4 let mobileCoBrowsingModule: UnbluMobileCoBrowsingModuleApi mobileCoBrowsingModule.stopMobileCoBrowsing { //... } failure: { error in //... } // it is also possible via a conversation let conversation: UnbluConversation conversation.stopMobileCoBrowsing { result in //... }
-
Changes to UnbluCallModule
The UnbluCallModule
has also undergone some changes in version 4.
-
Firstly, it provides a new delegate,
UnbluCallModuleDelegate
. -
As with
UnbluMobileCoBrowsingModuleProvider
,UnbluCallModuleProvider
no longer has anapi
instance you can use. To use the API of the module, you must now call thecreate()
function:// Version 3 let callModule = UnbluCallModuleProvider.module // Version 4 let callModule = UnbluCallModuleProvider.create()
-
Because of the lack of an
api
instance inUnbluCallModuleProvider
, checking for an active call works differently in version 4:// Version 3 UnbluCallModuleProvider.api.isCallActive { isActive in //... } // Version 4 let callModule: UnbluCallModuleApi callModule.isCallActive { isActive in //... } failure: { error in //... } // You can also check for an active call via a conversation let conversation: UnbluConversation let isCallActive = conversation.isCallActive
Other renamed or deprecated properties and functions
Version 3 | Version 4 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Set using |
|
|
|
|
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |
|
deprecated |