Contact usRequest a demo

Code setup and initialization

This article describes what you need to do so you can start to integrate Unblu features into your iOS app.

Framework composition

Unblu is divided into modules. Each module is distributed as an XCFramework, Apple’s binary framework format. Depending on your implementation, you may use some or all of them.

In total, there are six frameworks. You must always add the core framework:

  • UnbluCoreSDK.xcframework

The optional modules are:

  • UnbluMobileCoBrowsingModule.xcframework

  • UnbluOpenTokCallModule.xcframework

  • UnbluLiveKitCallModule.xcframework

  • UnbluCallKitModule.xcframework

  • UnbluFirebaseNotificationModule.xcframework

All the frameworks are dynamic binaries except for UnbluFirebaseNotificationModule, which is a static binary.

For all dynamic frameworks in the Frameworks, Libraries, and Embedded Content section of the Xcode project settings, choose either Embed & Sign or Embed Without Signing. For static frameworks, select Do Not Embed.

To add the files to an Xcode project, you must add them to your app target. You can obtain the files from the Unblu iOS mobile SDK GitHub repo, where you can also find instructions on installing the Swift package. Alternatively, you can drag the files directly into that section in Xcode.

You must also add some dependencies that aren’t included in the frameworks. Which dependencies you need depends on the Unblu modules you use.

The list below shows the dependencies you need to add to your app for the different Unblu modules. We recommend adding the dependencies using CocoaPods or Swift packages. If you opt for the Swift package manager, you should be aware of some potential pitfalls when integrating Firebase and LiveKit. For more information, refer to the relevant points in Known issues.

The list also includes links to instructions on how to integrate the libraries manually.

UnbluFirebaseNotificationModule

  • Dependency: Firebase Core

  • Version: ~> 7.0

  • Purpose: Base for Firebase messaging

  • CocoaPods podfile: pod 'Firebase/Core', '~> 7.0'

  • Manual integration Integrate without CocoaPods

  • Dependency: Firebase Messaging

  • Version: Derived from Firebase Core

  • Purpose: Needed for push notifications

  • CocoaPods podfile: pod 'Firebase/Messaging'

  • Manual integration link: Integrate without CocoaPods

UnbluLiveKitModule

  • Dependency : LiveKit WebRTC Provider

  • Version : ="104.5112.08"

  • Purpose : Needed for audio and video calls using LiveKit

  • CocoaPods podfile: pod 'WebRTC-SDK'

  • Manual integration link: Integrate without CocoaPods

For Firebase to work correctly, you must add the GoogleService-Info.plist file from the Firebase project to your app. Follow Google’s instructions on how to do so.

You needn’t set up Firebase in your code by calling FirebaseApp.configure(). The SDK does this automatically if you use the Unblu Firebase module.

Permissions

Various features require that you include certain permissions in your application’s Info.plist.

NSPhotoLibraryAddUsageDescription

Required to add downloaded images to the Photos app

NSPhotoLibraryUsageDescription

Required to upload images from the Photos app to a conversation

NSCameraUsageDescription

Required to upload images taken by the camera to a conversation. It’s also required by OpenTok and LiveKit for audio and video calls.

NSMicrophoneUsageDescription

Required by OpenTok and LiveKit for audio and video sessions.

You should also enable the following background modes:

Audio, Airplay, Picture in Picture, and Voice over IP

Required to continue calls when your app is in the background

Remote notifications

Required to receive all push notifications

You must specify these functions in the app description you provide for the AppStore verification process.

If a user permanently denies access to the camera, microphone, or speakers when the SDK requests it, the SDK doesn’t display a popup requesting permission anymore. To overcome this, the user must change the settings of their device, either reverting the access denial or granting access directly.

Code initialization

Before using the Unblu SDK in your code, you need to add the statement import UnbluCoreSDK to any Swift file that requires it.

Unblu instance

The two most important Unblu instance types you can create using UnbluCoreSDK are:

Both types inherit from UnbluClient, which provides shared functionality such as start and stop.

To create an instance of either UnbluVisitorClient or UnbluAgentClient, use the static functions Unblu.createVisitorClient and Unblu.createAgentClient, respectively.

The recommended procedure is to create an Unblu client instance as early as possible when you initialize your app and ensure that a reference to the instance is kept in memory, for example, by using a static global variable or adding a field to the UnbluApplication class.

The Unblu instance created this way isn’t a singleton. In principle, you can have more than one Unblu instance running at the same time. However, Unblu isn’t designed to work this way and doing so is strongly discouraged. You should implement your own solution for managing the lifecycle of the Unblu instance.

Unblu client configuration

When creating an instance of the UnbluVisitorClient or UnbluAgentClient, you must provide a configuration. This is done by passing an instance of UnbluClientConfiguration to the Unblu.createVisitorClient and Unblu.createAgentClient functions, respectively. The UnbluClientConfiguration struct can be instantiated with the base URL of the Unblu server and the API key of the Unblu account.

Only a limited number of settings are configurable via the Unblu mobile SDKs. All configurations that are independent of the your app can be made through the Unblu Account Configuration interface. Refer to the documentation of UnbluClientConfiguration for an overview of all possible configurations and their effects.

The Unblu client instance only stores a copy of the configuration, so you can’t change the configuration via the reference alone. To reconfigure Unblu, you must create a new Unblu instance and pass in your new UnbluClientConfiguration.

To separate the configurations for the mobile visitor API, the mobile agent API, and the webpage where Unblu is integrated, you should use different API keys for each environment.

Authentication

If you need to pass authentication information to the Unblu iOS mobile SDK, you can use UnbluClientConfiguration.accessToken. Alternatively, you can set custom cookies.

Authorization

If the user is authenticated against an external OAuth 2.0 authentication server that provides the application with an authorization token, the use of this token for authorization is divided into two stages:

If the token isn’t valid, an error of the type UnbluClientErrorType.authorization is received in unblu(didReceiveError:description:). When this occurs, you must stop the API, assign a valid token, and start the API again. Refer to Starting and stopping below for more information on starting and stopping the API.

The service worker that sets the authorization header on all requests must be excluded from any firewall rules you have in place. This is to ensure that it’s accessible even when the header isn’t present. The URL to exclude is /unblu/sw/auth-header/v1/auth-header-sw.js.

How to implement the OAuth 2.0 protocol in your iOS application—​obtaining a token, refreshing it, selecting a refresh interval and so on—​is outside the scope of this documentation. For more information on this topic, refer to the Apple documentation:

Unblu client delegate

The Unblu client delivers events via delegation.

Both protocols inherit shared functionality from the UnbluClientDelegate protocol. The functions to adopt in these protocols are all optional and are there to inform you of specific events so you can take certain actions.

Make sure to assign your delegate before you call UnbluClient.start (see below).

One of the more important delegate functions to be aware of is unblu(didRequestShowUi reason: UnbluUiRequestReason, requestedByUser: Bool). If you’re using push notifications, we strongly recommend that you adopt this function in your implementation. Suppose there is a push notification when there is an incoming call. If the user opens the app by clicking the notification, Unblu calls this function and assumes that the app will display the UnbluView as soon as possible.

Starting and stopping

The UnbluClient instance provides the functions UnbluClient.start and UnbluClient.stop to start and stop the connection, respectively. As these functions are defined on the UnbluClient protocol, they’re available on both the UnbluVisitorClient and UnbluAgentClient.

Both functions accept a completion block that’s called with a Result type containing success or an error, depending on the outcome.

If the Result represents a success, the UnbluView starts rendering Unblu content and you can start new conversations, check agent availability and so on.

How soon Unblu is available for use after it’s started depends on the user’s connection speed.

If you’re using notifications, it’s also important to have started Unblu at least once, so that the SDK can deliver a device token (required for APNS connectivity) to the Unblu server. Without the device token, the Unblu server has no way to establish the link between a user and their device. You should therefore start Unblu as early as possible, ideally right after the user logs in.

If Unblu is no longer needed, call the UnbluClient.stop function. This terminates the connection and cleans up resources.