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-apping 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. For visitors, set the following configuration properties:

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-apping sessions.

The functions that start calls and mobile co-apping 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.

For the collaboration layers you can use once a conversation is running, refer to Mobile collaboration layers.

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

Private views and areas are part of mobile co-apping. For how to use them, refer to Mobile collaboration layers.

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.

Color mode

This is a preview feature. It may be subject to change or removal with no further notice.

To enable preview features, set com.unblu.platform.enablePreview to true.

For more information on preview features, refer to the Unblu release policy.

Your app can match the Unblu UI to its own light or dark theme. To set the color scheme of the Unblu UI, call UnbluClient.setColorScheme with one of the UnbluColorScheme cases. .light and .dark force the respective mode. .auto follows the device’s color setting.

Listing 1. Matching the Unblu UI to your app’s theme setting

/* Your app's settings screen calls this when the user picks a theme.
   `AppTheme` is your app's own type. */
func onAppThemeSelected(_ appTheme: AppTheme) {

    // Apply the theme to your own UI first.
    // ...

    let colorScheme: UnbluColorScheme
    switch appTheme {
    case .light: colorScheme = .light
    case .dark: colorScheme = .dark
    case .system: colorScheme = .auto
    }

    /* `unbluClient` is the client you created with
       `Unblu.createVisitorClient` or `Unblu.createAgentClient`. */
    unbluClient.setColorScheme(colorScheme)
}

When a change takes effect depends on the color scheme evaluation mode. File previews, the document collaboration viewer, and the signature view adopt the new color scheme immediately, even if they’re already on screen. The same applies to the Unblu indicators and the other windows the SDK displays over your app. The call UI always uses fixed dark colors, so the color scheme doesn’t affect it.

An app override lasts until the Unblu UI next loads. This happens when your app starts the Unblu client. The color scheme configured on the Unblu server then takes effect again.

To keep your app’s color scheme across a reload, apply it again in UnbluClientDelegate.unbluUiIsReady. The SDK calls this function every time the Unblu UI becomes ready.

Listing 2. Reapplying the color scheme after the Unblu UI reloads

func unbluUiIsReady() {
    /* `currentColorScheme` is the `UnbluColorScheme` your app last worked
       out from its own theme setting. */
    unbluClient.setColorScheme(currentColorScheme)
}

For the server configuration properties and how an app override interacts with them, refer to Color mode in the mobile SDK configuration article.

Document collaboration

For how to use the document collaboration layer in the iOS SDK, refer to Mobile collaboration layers.

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