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:
-
UnbluVisitorClient
— provides the necessary APIs for visitor-related actions -
UnbluAgentClient
— provides the necessary APIs for agent-related actions
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
This feature only functions correctly if you include WKAppBoundDomains
in your Info.plist file. There, list all the domains your app interacts with. If you omit a domain, the Unblu SDK won’t operate properly.
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:
-
First you need to assign a token to this
UnbluClientConfiguration.oauthToken
. You should pass this token before you callUnbluClient.start
. -
You need to refresh the token periodically using the method
UnbluClient.setOAuthToken
. This lets the application obtain a new access token and continue to work without prompting the user.
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 . If you set the SDK log level to DEBUG , you see information about the service worker state. Additionally, related information is available in the JavaScript console. |
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.
-
For the
UnbluVisitorClient
, adopt theUnbluVisitorClientDelegate
protocol in your app and assign it to theUnbluVisitorClient.visitorDelegate
property. -
For the
UnbluAgentClient
, adopt theUnbluAgentClientDelegate
protocol in your app and assign it to theUnbluAgentClient.agentDelegate
property.
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.