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

Requirements

Version 4 of the Unblu iOS mobile SDK supports the Unblu server version 7.x.x and Unblu Spark version 8.x.x.

If you use the SDK with Unblu 7.x.x, the minimum required iOS version is 14.5. If your project is on an earlier version, you must update to at least version 14.5.
If you use the SDK with Unblu Spark 8.x.x, the minimum required iOS version is 15. Earlier iOS versions aren’t supported by Unblu Spark 8.

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. Clean your Xcode project after this to make sure references are updated.

To install the Unblu iOS mobile SDK, drag the XCFrameworks you require into your Xcode project, then add them to your target. The available XCFrameworks are:

UnbluCallModule.xcframework
UnbluMobileCoBrowsingModule.xcframework
UnbluCoreSDK.xcframework
UnbluFirebaseNotificationModule.xcframework
UnbluVisitorSDK.xcframework

Make sure to check the box Copy items if needed when you copy the XCFrameworks to your project.

Initializing and configuring Unblu

The way Unblu is initialized and configured has changed in version 4.

Initializing Unblu

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 Configuring Unblu below.

Compare how to initialize Unblu in the code snippets below:

Listing 1. Creating a configuration and initializing Unblu

// Version 3
let visitorConfig = UnbluApiConfiguration(...)
try? UnbluVisitorApi.instance.configureApi(configuration: visitorConfig)
UnbluVisitorApi.instance.<property_name> (1)

let agentConfig = UnbluApiConfiguration(...)
try? UnbluAgentApi.instance.configureApi(configuration: agentConfig)
UnbluAgentApi.instance.<property_name> (1)

// Version 4
let visitorConfig = UnbluClientConfiguration(...)
let unbluVisitor = Unblu.createVisitorClient(withConfiguration: visitorConfig)
unbluVisitor.<property_name> (1)

let agentConfig = UnbluClientConfiguration(...)
let unbluAgent = Unblu.createAgentClient(withConfiguration: agentConfig)
unbluAgent.<property_name> (1)

1	Replace `<property_name>` with the appropriate property name

initApi() and deinitApi() are now called start and stop, respectively.

Listing 2. Initializing and deinitializing Unblu

// 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 regarding the handling of external links.

The externalLinkPatternWhitelist property is no longer available on the configuration object. It has been replaced by the externalLinkHandler property and the new UnbluExternalLinkHandler protocol.

For more information, refer to Whitelisting external links.

`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 that’s available as the view property on the Unblu client instance. The entire Unblu UI is rendered in this view.

Providing a UIView makes integrating Unblu into your application simpler. It also provides a greater degree of control over where the Unblu UI is displayed in your app. 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 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’s visible in your app. Unblu needs this information to display notifications correctly.

The UnbluView itself tries to work out whether it’s visible or not by reading its UIView.isHidden property. In some circumstances, however, this isn’t enough. For example, you might have another UIView on top of the UnbluView, thereby obscuring it from view.

In such situations, try as best you can to keep Unblu informed when the UnbluView is visible. There are two functions in the UnbluView that help with this:

In most cases, it isn’t necessary to use these functions, but you should be aware of when you integrate 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 from the UnbluClient.openConversation property. The property’s value is nil if no conversation is currently open.

Additionally, when a conversation is opened or closed, Unblu calls the function UnbluClientDelegate.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.

Listing 3. Comparison of event dispatching in 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 appropriate delegate.

Below is a list of the Notification types in version 3 and the functions provided by the delegate protocols that replace them in version 4.

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) {
    //...
  }
}

For information on additional delegate protocols you can adopt, refer to the iOS SDK reference documentation.

Changes to `UnbluCoBrowsingModule`

The UnbluCoBrowsingModule is now called UnbluMobileCoBrowsingModule. This change makes it more explicit which co-browsing layer the module manipulates.

There have been a number of other changes to the UnbluMobileCoBrowsingModule. UnbluMobileCoBrowsingModuleApi has a number of new APIs:

The module also has a new delegate, UnbluMobileCoBrowsingModuleDelegate, and a new struct for configuring the module, UnbluMobileCoBrowsingModuleConfiguration. For more information, refer to the iOS mobile SDK reference documentation.

The UnbluMobileCoBrowsingModuleProvider doesn’t have an api instance like the UnbluCoBrowsingModuleProvider in version 3 did. This affects several existing APIs:

To use the API of the UnbluMobileCoBrowsingModule, UnbluMobileCoBrowsingModuleProvider now provides the create(config:) function:

// Version 3
let coBrowsingModule = UnbluCoBrowsingModuleProvider.module

// Version 4
let mobileCoBrowsingModuleConfig = UnbluMobileCoBrowsingModuleConfiguration(...)
let mobileCoBrowsingModule = UnbluMobileCoBrowsingModuleProvider.create(config: mobileCoBrowsingModuleConfig)

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.

The UnbluCallModule provides a new delegate, UnbluCallModuleDelegate.
As with UnbluMobileCoBrowsingModuleProvider, UnbluCallModuleProvider no longer has an api instance you can use. To use the module’s API, you must now call the create() function:
Listing 4. Accessing the UnbluCallModule's API
```
// Version 3
let callModule = UnbluCallModuleProvider.module

// Version 4
let callModule = UnbluCallModuleProvider.create()
```

Because of the lack of an api instance in UnbluCallModuleProvider, checking for an active call works differently in version 4:

Listing 5. Checking for an active call

// 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 in a conversation
let conversation: UnbluConversation
let isCallActive = conversation.isCallActive

Other renamed or deprecated properties and functions

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

Table 1. Renamed and deprecated properties and functions
Version 3	Version 4
`UnbluVisitorApi.instance.startAudioCall()`	`UnbluConversation.startAudioCall()`
`UnbluVisitorApi.instance.startVideoCall()`	`UnbluConversation.startVideoCall()`
`UnbluVisitorApi.instance.isCallUiOpen()`	`UnbluConversation.isCallUiOpen`
`UnbluVisitorApi.instance.getOpenConversationId()`	`UnbluClient.openConversation`
`UnbluVisitorApi.instance.setNamedArea()`	`UnbluClient.namedArea`
`UnbluVisitorApi.instance.setCustomCookies()`	`UnbluClient.customCookies`
`UnbluVisitorApi.enableDebugOutput`	`UnbluClient.enableDebugOutput`
`UnbluVisitorApi.enableCapturingPerformanceLogging`	Set using `UnbluMobileCoBrowsingModuleConfiguration` when you create an `UnbluMobileCoBrowsingModule` instance
`UnbluVisitorApi.logLevel`	`UnbluClient.logLevel`
`UnbluVisitorApi.preventScrollingByKeyboard`	`UnbluClient.preventScrollingByKeyboard`
`UnbluVisitorApi.instance.showUi()`	deprecated
`UnbluVisitorApi.instance.uiWindowConfiguration`	deprecated
`UnbluVisitorApi.instance.preloadUi()`	deprecated
`UnbluVisitorApi.instance.isUiVisible`	deprecated
`UnbluVisitorApi.instance.setUiMargins`	deprecated
`UnbluVisitorApi.instance.uiBottomMargin`	deprecated
`UnbluVisitorApi.instance.uiTopMargin`	deprecated