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.

Framework Files

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.

  • UnbluCoreSDK.framework
  • UnbluCoreSDKResources.bundle
  • UnbluVisitorSDK.framework
  • UnbluVisitorSDKResources.bundle
  • UnbluAgentSDK.framework
  • UnbluAgentSDKResources.bundle

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. The UnbluCoreSDK.framework and 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.

Swift Compatibility

Objective-C

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.

Swift Versions

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.

Permissions

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. Either use import UnbluVisitorSDK or import UnbluAgentSDK.

AppDelegate

The AppDelegate of the app should inherit from the UnbluUiApplicationDelegate. This is needed for unblu to setup correctly the Firebase and push notification integration.

The UnbluUiApplicationDelegate implements some of the functions from the protocol UIResponder, UIApplicationDelegate, 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 on_ prefix. 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

The most important class of the visitor SDK is UnbluVisitorApi and of the agent SDK it is UnbluAgentApi. They provide an instance function, which can be used to get an instance of the API.

It is highly recommended to get an instance of the UnbluVisitorApi/UnbluAgentApi class inside the AppDelegate.application function by calling instance. 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 UnbluVisitorApi/UnbluAgentApi, it needs to be configured. The api can be configured using the function configureApi. 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.

Events

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 NotificationCenter. Inside the 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 Notification.userInfo member.

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 UnbluVisitorApi/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 deinitApi function.

Unblu UI

The UnbluVisitorSDK/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 UnbluVisitorApi/UnbluAgentApi. 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 WebView. 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.

Note that there are several functions like opening a conversation or starting and audio/video call require to open the UI at least once so that the corresponding part was loaded in the javascript. You can find details about in the documentation of each function and the error callbacks may need to implement this case.

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.

UnbluUiButton

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.

Private Views

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 removePrivateView function.

Custom Cookies

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 setCustomCookies function. 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.

Named Areas

Similar to a web page, the named area feature is also available for the mobile SDKs. See Named Area for more details.

A named area can either be set via the UnbluApiConfiguration before initializing the API. Or else it can be set by calling setNamedArea on the UnbluVisitorApi/UnbluAgentApi instance.

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.

  • deploycloud
  • deployonprem

results matching ""

    No results matching ""