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.

Conversely, you can add a back button to the Unblu UI that enables the user to explicitly hide the Unblu UI. The config property that enables this behavior is com.unblu.visitor.ui.showOverviewActionBarCollapseAction on the visitor side, and com.unblu.agent.mobile.ui.showInboxActionBarCollapseAction on the agent side.

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.

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 in UnbluMobileCoBrowsingModuleApi
delegate in UnbluCallModuleApi
delegate in UnbluFirebaseNotificationCoordinator
visitorDelegate in UnbluVisitorClient
agentDelegate in UnbluAgentClient

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 before UnbluClient.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 using UIDocumentInteractionController to display PDFs and want Unblu to capture them within mobile co-browsing sessions, display PDFs using either WKWebView or the Apple PDFKit framework instead.
SFSafariViewController isn’t compatible with the Unblu mobile co-browsing engine.