Working with the Unblu iOS mobile SDK
The sections below provide some pointers on working with the Unblu iOS mobile SDK.
UnbluView
All Unblu UI content is rendered into a subclass of UIView
called UnbluView
. It shows all existing conversations. These conversations can be used to chat and make calls.
The view is accessible via the UnbluClient.view
property. You must add the UnbluView
to a view hierarchy somewhere in your app for it to be visible on the device. It’s up to you to define the view’s size and position within the context of your application. As a rule of thumb, you should use the full width of the screen and at least half of the screen’s height to ensure the content is rendered correctly.
You shouldn’t add the UnbluView
into your app view hierarchy before calling UnbluClient.start
. Wait for the success callback to trigger before adding it to your view hierarchy. If you don’t, some UI elements may not be available until the user hides the Unblu UI and displays it again.
Unblu maintains the UnbluView
in a hidden view hierarchy until you add it to your own view hierarchy. Likewise, if you remove the UnbluView
from your view hierarchy at runtime, Unblu keeps it alive until you call UnbluClient.stop
.
Sometimes, Unblu requests that you show the UnbluView
via the delegate, for example, because there’s an incoming call or mobile co-browsing just started. It’s up to you to respond to these requests and take the user to wherever you render the`UnbluView` in your app.
-
Set com.unblu.visitor.ui.showOverviewActionBarCollapseAction to
true
. -
Set com.unblu.visitor.mobile.ui.overviewActionBarCollapseActionDisplayMode to BACK_BUTTON.
If you set it to COLLAPSE_BUTTON, you should review the configuration property com.unblu.visitor.mobile.ui.allowCollapseButton as well.
For agents the relevant configuration property is com.unblu.agent.mobile.ui.showInboxActionBarCollapseAction.
In this situation, a hide request is sent which you must respond to (see UnbluClientDelegate.unblu(didRequestHideUi reason: UnbluUiHideRequestReason, conversationId: String?)
for more information). For the hide request, you must enable the configuration property com.unblu.conversation.ui.autoCollapseIndividualUiOnLayerActivation.
If there’s an issue with the Unblu UI, be aware that the UI is rendered in a WKWebView
. This means you can attach the local Safari to check for error logs. With iOS WebViews, it isn’t possible to see the logs inside the normal debugger console.
Conversations
The UnbluConversation
protocol provides the neccessary APIs to interact with conversations in Unblu. This includes actions such as opening and closing the conversation, starting audio or video calls, and launching mobile co-browsing sessions.
The functions that start calls and mobile co-browsing sessions require the presence of the UnbluCallModule (and a WebRTC provider) or UnbluMobileCoBrowsingModule , respectively. If the required module isn’t registered to the Unblu instance, an error is thrown at runtime. |
The conversation currently open is always available via the UnbluClient.openConversation
property. If no conversation is currently open, the property’s value is nil
.
If you wish to be notified when a conversation is opened or closed, adopt the unblu(didChangeOpenConversation openConversation: UnbluConversation?)
function in your delegate implementation.
The main functions on the UnbluClient
relating to conversations are:
Additionally, the UnbluVisitorClient
provides:
It’s also possible to intercept conversation-related activity by setting the UnbluVisitorClient.conversationInterceptor
to an object that conforms with the UnbluConversationInterceptor
protocol.
Private views and areas
As part of the UnbluMobileCoBrowsingModule
, Unblu provides a simple way to specify views that shouldn’t be displayed on the remote side. After adding a view’s tag, the view is automatically overlaid by an image before the screen is transmitted to the remote side.
The UnbluMobileCoBrowsingModuleApi
provides the function addPrivateView
which takes a tag as its input parameter. You can define a different tag for each view.
You can make a view visible to the remote side again by calling the removePrivateView
function, which is also exposed on the UnbluMobileCoBrowsingModuleApi
.
The SDK also provides a way to specify areas that shouldn’t appear on the remote side. This is especially useful if you use a webView
or a canvas
-based framework to render your UI. Often, there aren’t any tags on the view that could be used to overlay the element during co-browsing.
To hide an area, the UnbluMobileCoBrowsingModuleApi
provides the function addPrivateArea
. The function take parameters that specify the area’s ID, the x and y coordinates of the upper left-hand corner, and its width and height. Each private area has its own ID.
After an area is added, it is automatically overlaid by an image before the screen is transmitted to the remote side. You can make an area visible to the remote side again by calling the function removePrivateArea
, which is also exposed on the UnbluMobileCoBrowsingModuleApi
.
Animations and private views and areas
If you use animations to transition from a view that contains a private view or area, the overlay may not conceal the content during the entire transition.
If you know your app uses animations in views that contain private views or areas, you should take measures to ensure that the content isn’t exposed during the animation. For example, if you know the animation is always horizontal, you might make the overlay larger, so that it covers the area the concealed content traverses during the animation.
Custom cookies
You can define custom cookies that should be sent with each request to the Unblu server. This can be done initially with the UnbluClientConfiguration
, or by setting the cookies on your Unblu client instance dynamically through the UnbluClient.customCookies
property.
When the Unblu client is started, the last cookies configured are always used. If the client is already started, cookies with the same name are overridden, and any new cookies are added. Cookies set here survive on the Unblu instance even when the client is stopped. They’re applied again to the WebView when the instance is started again. As such, if the client is started again, the last defined cookies are used.
Named areas
You can set a named area in the UnbluClientConfiguration
before starting the client or with the UnbluClient.namedArea
property.
When you should set the named area depends on what it’s used for:
-
If your app needs settings configured in the named area scope, you must set the named area before starting the client so that the configuration specific to the named area is also loaded on initialization.
You could, however, also consider changing the configuration in the API key scope rather than the named area.
-
If named areas are only necessary for assigning conversation requests to the right queues in the Agent Desk, you can set the named area later at any time before starting a new conversation. A named area set this way has no effect on existing conversations.
File uploads
You can restrict the types of file that users may upload to conversations with the following configuration properties:
These options affect the Unblu mobile SDKs, too. However, the restrictions in place aren’t reflected in the iOS UI. Use com.unblu.filemanager.fileTypeInputTagHint to provide the iOS with a hint as to which file types a user may upload.
For more information, refer to Configuring file uploads.
Visitor data
The term "visitor data" refers to data about a visitor that isn’t directly related to Unblu but may be required by some other system. This could be something like information about where exactly a visitor started the conversation that’s needed by a backend system to decide how to proceed. Conversely, it might be the outcome of some interaction with a backend system that influences the frontend in some way.
You can set visitor data in the iOS SDK by passing it in as a parameter of the startNewConversation
function on the UnbluVisitorClient
instance. Alternatively, use the function setVisitorData
.
Working with keyboards
If your app uses SwiftUI, the height of the container that the UnbluView
is added to is automatically changed to avoid keyboard overlap.
If you use UIKit, you must ensure the height of the container is changed by adding observers to the events keyboardWillShowNotification
and keyboardWillHideNotification
, where the height should be adjusted according to the height of the keyboard.
Weak references
The variables listed below are weak references. You must reference the instances you assign to these variables before you assign them.
-
delegate
inUnbluMobileCoBrowsingModuleApi
-
delegate
inUnbluCallModuleApi
-
delegate
inUnbluFirebaseNotificationCoordinator
-
visitorDelegate
inUnbluVisitorClient
-
agentDelegate
inUnbluAgentClient
Known issues
-
LiveKit has its own version of the WebRTC framework. The Unblu iOS mobile SDK needs a specific version of this framework that matches the version of the LiveKit framework it uses. If you add the wrong version, it won’t work.
Unfortunately, the Swift package manager only provides a couple of the latest versions of the LiveKit WebRTC framework. CocoaPods, on the other hand, has all versions available. If you use LiveKit in your app, you should therefore use CocoaPods to the LiveKit dependency.
-
The
UnbluFirebaseNotificationModule
needs to export symbols from the Firebase framework it depends on. In Swift, a static framework that exports symbols from its own dependencies can lead to conflicts and complexities in symbol management.If such problems arise, the error message looks something like this:
Failed to build module 'UnbluFirebaseNotificationModule'; this SDK is not supported by the compiler (the SDK is built with 'Apple Swift version 5.7.2 (swiftlang-5.7.2.135.5 clang-1400.0.29.51)', while this compiler is 'Apple Swift version 5.9 (swiftlang-5.9.0.128.108 clang-1500.0.40.1)'). Please select a toolchain which matches the SDK.
To avoid this issue, you should add the Firebase dependencies to the application via CocoaPods. This method uses the source code, so the problem doesn’t arise. Furthermore, make sure you open the workspace file in Xcode, not the project file.
-
If you add the
UnbluView
to your app’s view hierarchy beforeUnbluClient.start
has completed successfully, some UI elements may not be available until the user hides the Unblu UI and displays it again.For more information, refer to the relevant section above.
-
If you send
Encrypted
notifications, you should use the notification service extension. If you don’t, notifications may not be delivered if the user manually kills the app and then relaunches it. -
UIDocumentInteractionController
isn’t compatible with the Unblu mobile co-browsing engine. If you’re usingUIDocumentInteractionController
to display PDFs and want Unblu to capture them within mobile co-browsing sessions, display PDFs using eitherWKWebView
or the Apple PDFKit framework instead. -
SFSafariViewController
isn’t compatible with the Unblu mobile co-browsing engine.
See also
-
For more information on working with the Unblu iOS mobile SDK, refer to the Unblu iOS mobile SDK reference.