Mobile SDK iOS Integration
This section describes how the visitor/agent SDK can be integrated into an iOS app. It describes step by step from adding the framework files to use the api, whereby it gives some hints to get a good user experience and avoid some common pitfalls.
unblu provides different framework files for the different platforms: simulator, real device and a fat framework.
A fat framework contains both platforms and is typically the best choice. However, for a release in the Apple AppStore the x86 framework must be removed using Apple’s “lipo” tool as Apple does not allow binaries for the simulator. There are several scripts on the internet that can be used to strip the simulator part away while building the app. Does scripts need to be added to the build phases of the app.
In total there are 5 files.
The agent and visitor SDK are build as static framework files.
Therefor it is required that the resources of a framework file is additionally provided via bundle files.
UnbluCoreSDKResources.bundle need to be added always.
Depending on the type of the app, if it should be for a visitor or for an agent, either the framework and bundle for the visitor or agent sdk needs to be added too.
To add the files to an xcode project, they can be dragged and dropped to Xcode. Automatically the framework files get added to the project settings Build Phases > Link Binary With Library and the bundle files get added to the Build Phases > Copy Bundle Resources. Additionally the framework files need to be added manually to the settings of the project in General > Embedded Binaries.
As unblu only provides static frameworks, it does not deliver the dependencies with them. The following table shows the dependencies which need to be added to the app. We prefer to add the dependencies via CocoaPods, but the tables also gives a link on how to integrate the library manually.
|Name||Version||CocoaPods Podfile||Manual Integration Link||Purpose|
|OpenTok||~> 2.15.3||pod ‘OpenTok’, ‘~> 2.15.3’||https://tokbox.com/developer/sdks/ios/ Using the SDK||Needed for audio/video calls|
|Firebase Core||~> 5.4||pod ‘Firebase/Core’, ‘~> 5.4’||https://firebase.google.com/docs/ios/setup#frameworks||Base for firebase messaging|
|Firebase Messaging||Derived from Firebase Core||pod ‘Firebase/Messaging’||https://firebase.google.com/docs/ios/setup#frameworks||Needed for push notifications|
For Firebase to work correctly, it is also necessary that the GoogleService-Info.plist file from the Firebase project is added to the app. Please follow the instructions from here to add it to your project. Important to know is also, that it is not necessary to setup Firebase in your code. This is automatically done by the SDK when push notifications are enabled.
The frameworks provides from unblu are written in Swift and not with Objective-C as Swift is the new standard from Apple. In theory Swift code can be used in Objective-C. But actually there are some limitations. E.g. enums in Swift need to have a raw type of Int. Therefor it is not simply possible to use the SDKs in an Objective-C environment. The project which was formally an Objective-C project, would need to be changed to a Swift project, which mainly uses Objective-C. Then the usage of an SDK is required to be wrapped into a Swift helper, which can be used in Objective-C.
In 2014 Apple wrote : “… if your project uses frameworks to share code with an embedded extension, you will want to build the frameworks, app, and extensions together. It would be dangerous to rely upon binary frameworks that use Swift — especially from third parties. As Swift changes, those frameworks will be incompatible with the rest of your app. When the binary interface stabilizes in a year or two, the Swift runtime will become part of the host OS and this limitation will no longer exist.”
The binary interface has not, unfortunately, ‘stabilized’ yet. This means that the Swift version of the used unblu SDK must match the Swift version of the App. In case the used unblu SDK from unblu was build with an older version, the project could be change to a different Swift Language Version inside the project compiler settings. This, unfortunately, does not work always. In this case there are two possibilities. First download an older version of the XCode Toolchain to be compatible again. Second update to a newer version of the unblu SDK.
Typically unblu always tries to provide the SDKs always for the newest Swift version. If you need the unblu SDK for an older Swift version, because the app is still on an older version, you can ask the unblu support for it.
The following permissions are required in the applications info.plist for different features.
|Permission Key||Required for Feature|
|NSCameraUsageDescription||Required for audio and video sessions (also for plain audio sessions)|
|NSMicrophoneUsageDescription||Required for audio and video sessions|
|NSPhotoLibraryAddUsageDescription||Required to add downloaded images to photos app|
|NSPhotoLibraryUsageDescription||Required to upload images from photos app into a conversation|
Code Setup and Initialization
To use unblu the SDK in the code of an application, it is necessary to specify the import of the corresponding SDK.
import UnbluVisitorSDK or
AppDelegate of the app should inherit from the
This is needed for unblu to setup correctly the Firebase and push notification integration.
UnbluUiApplicationDelegate implements some of the functions from the protocol
MessagingDelegate it implements.
For some of the functions it is possible to override them again in the
AppDelegate, but then it is typically necessary to call the super implementation.
Some functions, e.g. for the messaging are not possible to override again.
If the app itself uses push notifications, the
UnbluUiApplicationDelegate provides those functions with an
The benefit of this is, that the used unblu SDK checks for unblu push notifications.
Only for notifications which are not for the SDK, it calls the
on_ prefixed functions.
This means the app itself does not need to filter out the unblu push notifications.
If for some reason it is not possible to use the
UnbluUiApplicationDelegate as base class, there are several things which are needed to do manually.
E.g. Firebase and its messaging part needs to be configured;
The handling of app launches from a push notification click and the handling of new incoming push notifications needs to be forwared to the SDK.
This is not covered by this documentation. Please ask the unblu support for more details on it.
Unblu API Instance
It is highly recommended to get an instance of the
UnbluAgentApi class inside the AppDelegate.application function by calling
In this way the SDK can register itself for all required app events before one of them is fired.
Note: The UnbluApi is defined as a singleton, so there is only one instance of it.
Therefor further usages of the
instance member will not create additional instances.
Unblu API Configure
Before using the instance of the
UnbluAgentApi, it needs to be configured.
The api can be configured using the function
It accepts an instance of UnbluApiConfiguration.
This class can be instantiated with the base url of the unblu server and the API key of the unblu account.
For all possible configurations and their effects, take a look at the documentation of UnbluApiConfiguration. There is only a very limited set of configurations which can be done on via the unblu SDKs. All configurations which are independent of the client (the app) can be done via the unblu agent desk.
To properly separate the configuration for the mobile visitor and agent SDK and also from configurations done for the webpage where unblu is integrated, we recommend to use different API Keys for each environment.
Inside the unblu API instance, only a copy of the configuration is stored.
So it can not be changed by the reference.
A new call to
configureApi has to be done.
Configuring the API can only be done while it is not initialized and it would throw an exception if it is already initialized.
Normally the configuration should only be done once at the beginning.
Before you initialize the API you should register for events in order to be sure not to miss any.
In iOS this can be done by using
Notification.Name object all unblu events are available with “Unblu” as the prefix.
Detailed information on the events can be found inside the UnbluEventApi and UnbluUiEventApi class.
They also provides constants to get the values out of the
A very important event is the UiVisibilityRequest. As soon as push notifications are used, it is recommended to listen for this event. E.g. there is a push notification, when there is an incoming call. If the user opens the app by clicking the notification, the SDK directly will fire this event and assumes that the app will initialize and opens the unblu UI as soon as possible.
Initialization and Deinitialization
To initialize an instance of
UnbluAgentApi the function
initApi can be called.
The callback parameters can be used to get information about success and errors. Additionally the Error event can be used as described in the Events section. Regarding on errors it is highly recommended to register for the api error event globally to not miss an error as they can happen independent of an explicit call to the api.
After the success callback was triggered, the unblu UI can be displayed, new conversations can be started, agent availability can be checked etc…
The API can either be initialized directly or only on demand. For example when co-browsing is needed. Note that when the API is initialized on demand the SDK will take some time until it is ready and a session can be started. Additionally if push notifications are used, it is required at least once to have the API initialized. Otherwise the unblu collaboration server has no connection between a user and the device. Therefor in general we recommend to initialize the API as soon as it is possible (directly after login).
If the SDK is no longer needed and everything should get cleaned up, there is the
UnbluAgentSDK provides an unblu UI which shows all existing conversations and which can be used to chat and make a call inside a conversation.
This UI can be displayed on top of the app UI.
It is controlled also be using the instance of the
It is possible to open/close and change its top/bottom margin.
Additionally it can be checked if it is open or if a call is currently displayed.
For those states there are also events defined in the UnbluUiEventApi.
If there is an issue with the unblu SDK, please be aware that the UI is rendered inside a
Therefor it is possible to attach the local Safari to check if for error logs.
It is a limitation of the iOS WebViews that it is not possible to see the logs inside the normal debugger console.
If, at some point, it is likely that the user would use the unblu UI, we would recommend you preload the UI.
This can be achieved by either configuring to preload the UI with the initialization (see UnbluApiConfiguration) or by calling
preloadUi if the API was already initialized previously.
Next to the Unblu UI, the SDKs provide the class UnbluUiButton. This button UI can be placed inside the app UI either via the Xcode Interface Builder or directly in the Code. Typically the button will be placed in the lower right corner of the screen.
The user can use the button to toggle the visibility of the unblu UI.
The button displays a number of unread chat messages when new messages arrive and the UI is hidden. Additionally it can automatically set the bottom margin for the unblu UI and places a semi transparent background behind it.
To integrate it, please follow the instructions in the UnbluUiButton class documentation.
The SDKs provides a simple way to add specific views which should not be shown on the remote side.
To do this, the
UnbluVisitorApi provides the function
addPrivateView which takes a tag.
A tag can be defined for each view.
After a view tag is added, it is automatically overlaid by an image before the screen is transmitted to the remote side.
It is also possible to make a view visible to the remote side again by calling the
It is possible to define custom cookies, which should be sent with each request to the unblu server.
This can either be done (initially) by using the UnbluApiConfiguration or by setting the the cookies dynamically via the
Before the API is initialized, always the last cookies configured are used.
If the API is already initialized, cookies with the same name are overridden and new cookies are added.
The previously-defined cookies will stay until the API is de-initialized.
If the API is then initialized again, only the last defined cookies are used again.
If a named area is set before initializing the API, also the specific configuration for it is loaded on initialization. If it is later set, it only changes the requests for new conversations in the agent desk queue in the way that the agent can filter by the named area. The named area has no effect for existing conversations.
As consequence, it is important to know if there will be specific configuration on the named area scope. In this case the named area has to be configured/set in the SDK before initializing the API, but then it should be always considered to change the configuration on API Key level. If a named area are only used for the queue, it can be set at any time before starting a new conversation.