Contact usRequest a demo

Unblu modules

Unblu provides three modules that extend the default functionality provided by the UnbluCoreSDK:

  • UnbluMobileCoBrowsingModule

  • UnbluCallModule

  • UnbluFirebaseNotificationModule

The modules correspond to XCFrameworks of the same name, except for UnbluCallModule, which is embedded in CoreSDK. UnbluCallModule then uses OpenTok or LiveKit dynamically, depending on the configuration of the Collaboration Server.

UnbluCallModule

The UnbluCallModule is a bridge between the CoreSDK module and different WebRTC providers. It’s embedded in CoreSDK. The XCFrameworks named UnbluOpenTokCallModule and UnbluLiveKitCallModule consist of OpenTok and LiveKit providers. The UnbluCallModule provides the necessary functionality to make audio and video calls.

To create an instance of the UnbluCallModule, call the UnbluCallModuleProvider.create static function. You can then register the instance by calling the UnbluClientConfiguration.register function.

The bridge only works if at least one XCFramework WebRTC provider is added to the project: UnbluOpenTokCallModule.xcframework or UnbluLiveKitCallModule.xcframework. You can also add both providers to the project. This allows you to use either of them depending on the Collaboration Server’s settings.

UnbluCallKitModule

The UnbluCallKitModule provides late binding to the iOS CallKit module. If you don’t need the call module, don’t add it to the project. This helps to avoid questions about CallKit in China during the AppStore submission process.

If you’re going to offer VoIP calls, you should add this module to your project along with at least one of the WebRTC providers, UnbluLiveKitCallModule or UnbluOpenTokCallModule.

Even if this module is added, it doesn’t work in China. This is due to restrictions in place on Apple’s part. The restrictions work according to the region specified in the phone’s settings.

VoIP calls still work in China, but instead of the standard iOS call UI, incoming call notifications arrive as regular notifications.

UnbluMobileCoBrowsingModule

The UnbluMobileCoBrowsingModule provides co-browsing functionality It enables real-time interaction and collaboration between an agent and a visitor on the visitor’s device screen.

To create an instance of the UnbluMobileCoBrowsingModule, call the UnbluMobileCoBrowsingModuleProvider.create static function, passing in a configuration object of type UnbluMobileCoBrowsingModuleConfiguration. You then register this module via the UnbluClientConfiguration.register function.

UnbluFirebaseNotificationModule

If you use Firebase to receive push notifications from Unblu, you need to import the UnbluFirebaseNotificationModule.

You needn’t to register the UnbluFirebaseNotificationModule.

Using UnbluFirebaseUIApplicationDelegate

As part of the Firebase module, Unblu provides some helper classes to make integration with Firebase easier. One of the classes, UnbluFirebaseUIApplicationDelegate, can serve as the base class for your AppDelegate:

import UnbluFirebaseNotificationModule

class AppDelegate: UnbluFirebaseUIApplicationDelegate {

}

If you choose to subclass UnbluFirebaseUIApplicationDelegate, Unblu can configure Firebase push notifications for you automatically.

To receive push notification data in your AppDelegate, you can override a number of functions:

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any])
{

}

override func on_application(
    _ application: UIApplication,
    didReceiveRemoteNotification userInfo: [AnyHashable: Any],
    fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
{

}

To receive the FCM token provided by Firebase, override the following function:

override func on_messaging(
    didReceiveRegistrationToken fcmToken: String?)
{

}

Manual integration

If you choose not to use UnbluFirebaseUIApplicationDelegate, you must manually integrate with Firebase and pass relevant push notification data to Unblu, such as device tokens and remote notification data, when it’s received. To do so:

  1. Enable push notifications in your Xcode project.

  2. Create a VoIP Services certificate in the iOS Developer Center.

  3. Enable the Voice over IP and Remote notifications background modes for your app.

    Firebase integration requirements aren’t listed here.
  4. Initialize the UnbluFirebaseNotificationCoordinator class in the AppDelegate class and assign a reference to an instance of the UnbluFirebaseNotificationCoordinator class to the AppDelegate class variable.

    Listing 1. Example of the AppDelegate class
    class AppDelegate {
    
    var coordinator: UnbluFirebaseNotificationCoordinator?
    //...
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions)
         coordinator = UnbluFirebaseNotificationCoordinator()
    
    }
    //...

    Inside this initialization, the SDK attempts to register for push notifications and PushKit notifications. The UnbluFirebaseNotificationCoordinator class also contains a reference to the UnbluNotificationApi class. If you don’t have permission for push notifications, a dialog box is displayed asking for permission.

    UnbluFirebaseNotificationCoordinator
  5. Register to receive push notifications and PushKit notifications.

    If you register to receive PushKit notifications, you need to initialize the UnbluNotificationApi class. Store a reference to an instance of this class in a place that isn’t disposed of while the application is running, for example, in a variable in the AppDelegate class. This is because the PKPushRegistryDelegate delegation protocol is provided inside the class. If there’s a reference to it on the stack, iOS functions can’t access it.

    The code sample below shows how to initialize the UnbluNotificationApi class correctly.

    Listing 2. Example of a correctly initialized UnbluNotificationApi class
    class AppDelegate {
    
    var notificationApi: UnbluNotificationApi?
    //...
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions)
         notificationApi = UnbluNotificationApi.instance
    }
    //...

    This code sample shows an example of what you shouldn’t do.

    Listing 3. Example of an incorrectly initialized UnbluNotificationApi class
    override func application(_ application: UIApplication, didFinishLaunchingWithOptions)
         UnbluNotificationApi.initialize()
  6. Set the device token:

    override func application(_ application: UIApplication, didFinishLaunchingWithOptions)
         notificationApi = UnbluNotificationApi.instance
         notificationApi.deviceToken = <your token>

    For PushKit notifications, the device is registered in this call:

    	notificationApi = UnbluNotificationApi.instance

    You don’t need a client instance to use the NotificationApi. You do, however, need a client instance to send the device token to the Unblu Collaboration Server.

    The NotificationApi is initialized in the UnbluCoreApi class. You must access the static variable directly:

              UnbluNotificationApi.instance.deviceToken = <your token>

    The instance of the UnbluNotificationApi class where the token is stored is created and initialized the first time it’s accessed.

APNs integration without Firebase

You can use Apple’s Push notification servers without the Firebase middleware. To do so, you must:

  1. Enable this option in the Unblu Collaboration Server with the configuration property com.unblu.mobile.push_notification.enableApnsForAllNotifications.

  2. Don’t add UnbluFirebaseModule to your app, and skip all the steps related to this module.

  3. Add the following code to the AppDelegate class and adapt it for your application:

    func application(_ application: UIApplication,
                            didFinishLaunchingWithOptions launchOptions:
                            [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        UIApplication.shared.registerForRemoteNotifications()
    }
    
    func application(_ application: UIApplication,
                        didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
        let token = deviceToken.map { String(format: "%02x", $0) }.joined()
        UnbluNotificationApi.instance.deviceToken = token;
    }
    
    func application(_ application: UIApplication,
                        didReceiveRemoteNotification userInfo: [AnyHashable: Any]) {
        do {
            try UnbluNotificationApi.instance.handleRemoteNotification(userInfo:
                    userInfo,withCompletionHandler: {_ in
            })
        } catch {
            // If you're here, you've received a notification unrelated to Unblu
        }
    }
    
    func application(_ application: UIApplication,
                        didReceiveRemoteNotification userInfo: [AnyHashable: Any],
                fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
        do {
    
            try UnbluNotificationApi.instance.handleRemoteNotification(userInfo:
                        userInfo,withCompletionHandler: {_ in
            })
        } catch {
            // If you're here, you've received a notification unrelated to Unblu
        }
    }

    As you can see, you must register to receive remote notifications. When you receive a token, assign it to an instance variable deviceToken of the UnbluNotificationApi class. When you receive notifications, pass them to the appropriate methods of the UnbluNotificationApi instance.

    For more information, refer to Registering your app with APNs.

Sample log messages

Some log messages you may encounter when manually integrating with Firebase and passing relevant push notification data to Unblu are listed below with their meaning and origin.

The following messages are logged on the Unblu Collaboration Server:

pushRegistry(_:didUpdate:for:): <token>

The device was successfully registered and received the PushKit token.

pushRegistry(_:didInvalidatePushTokenFor:for:): <token>

The device received a command to invalidate the PushKit token.

Successfully sent PushKit Notification to device

PushKit notification was sent to initiate a VoIP call.

Successfully sent MISSED_CALL Push Notification to device

A push notification was sent.

The following messages are logged by the Unblu iOS mobile SDK:

registerPushNotificationToken received shared

The device was successfully registered and received a secret key for the PushNotificationVersion = Encrypted.

Prevented emitRegisterPushKitNotificationToken, because API is not initialized. Value: nil

Either the token wasn’t received and the API was initialized, or the API wasn’t initialized.

Successfully registered for pushkit notifications

The device token is received only if it’s a new token and the token isn’t null.

Successfully registered for remote notifications

The device token is received only if it’s a new token and the token isn’t null.

See also