WebRTC Calls and UI

Find more info about Voice/Video Calls and WebRTC features in Infobip docs.

• Intro
• Quick start guide
• Important notes
• Stopping and restarting the service
• Taking control over the calls
• Customising the calls UI
• Troubleshooting

Intro

WebRTCUI is an easy to use, plug-and-play component, that allows you to connect to Infobip RTC by just invoking one single method. This assumes, though, that the initial setups of Mobile Push Notifications and the Infobip RTC exists in both, your account and your mobile app profile.

WebRTCUI takes care of everything: the registration of your device (in order to receive and trigger calls), the handle of the calls themselves, and offers you a powerful user interface with all the features your customer may need: ability to capture video through both, front and back camera, option to mute and use the speaker, ability to capture and share the screen of your mobile device, option to minimise the call UI in a picture-on-picture mode, and more.

WebRTCUI also allows you to take control in any step of the flow, if you wish or needs so: you can intercept the calls to checks its content, become a delegate for the WebRTC service, use our UI to build on top of it, or use your own custom user interface to handle the calls; it is up to you.

Quick start guide

1. Make sure you have setup the core of Mobile Messaging SDK and that you are able to successfully receive push registration Ids (the console debug logs will give you a hint about it). You will need the mobile push application code, and the webrtc application id, both retrievable from the Customer Portal, as seen in the following pictures:

2. Enable, in your Xcode target, under "Signing & Capabilities", the background modes: "Voice over IP", "Background fetch" and "Remote notifications".

3. Add the WebRTCUI subpod to your Podfile, and do pod install (or pod update):

   pod 'MobileMessaging'
   pod 'MobileMessaging/WebRTCUI'

4. Enable calls in the MobileMessaging SDK initialisation:

    MobileMessaging.withApplicationCode(
            <your push application code>, notificationType: .alert)?.withCalls(<your webrtc application Id>).start()
    /*
    Alternative including calls and chat components (it needs pod 'MobileMessaging/InAppChat')
    MobileMessaging.withApplicationCode(
            <your push application code>, notificationType: .alert)?.withInAppChat().withCalls(<your webrtc application Id>).start()
    */

5. That's it! Your app is now set to receive calls in a real device. If you wish to change the application code/ids above, we suggest to uninstall and reinstall the app, as those values are linked to the app installation.

Important notes

While WebRTCUI is plug-and-play, there are few things you should handle in your app before it is submitted to the Apple Store, in order to avoid problems:

1. We suggest you ask for permissions for microphone use in your app before a WebRTC call is triggered. This will avoid the case where a first call is received, but the client is forced-muted until the permissions are granted. Camera permissions are not that critical. In any case, our WebRTCUI component will prompt an alert for the cases above if a lack of the needed permissions is detected.

AVAudioSession.sharedInstance().requestRecordPermission({ granted in
            if !granted { print("Microphone permission denied.") }
            DispatchQueue.main.asyncAfter(deadline: .now() + 1) {
                AVCaptureDevice.requestAccess(for: AVMediaType.video) { granted in
                    if !granted { print("Camera permission denied.") }
                }
            }
        })

2. iOS will always display, for incoming calls, the system UI (either banner of fullscreen). This is unavoidable, though it will be in background when your app is in foreground. But that's not the case when your device is locked: the operating system will offer its UI, and there will be a button that links the call to your app. This button needs an icon provided by you, that must be a png with alpha channel. The system will present it as a monochrome equivalent icon, so consider this fact (colours will be ignored) when choosing its design. See the setup of it in the ChatExample project included in the SDK:

    MobileMessaging.webRTCService?.callAppIcon = UIImage(named: "alphaLogo")

3. The WebRTCUI allows you to set the sounds your app will produce for inbound ringing, outbound ringing and call disconnected. See the section of customisation and the Chat Example for more details. The customisation for this sounds is entirely optional - system sounds or the default WebRTCUI sounds will be used if undefined otherwise.

4. WebRTC is not allowed in the People's Republic of China. Offering it risks an Apple Store rejection. If you are releasing world wide or in that territory, you need to add, in your app release notes in AppStoreConnect, a text similar to: "In this version and onwards, we do not use CallKit features for users in China. We detect the user's region using NSLocale". Our WebRTCUI already checks the region and disable its functionality for you.

5. Currently, WebRTCUI is oriented to calls with Infobip Conversation's agents; P2P calls and channel specific call types are not yet supported (though you can still manually integrate them with Infobip RTC SDK.

Stopping and restarting the service

1. The method withCalls() used for the initialisation of the MobileMessaging in the Quick start guide above will register for calls whenever the app has received a push registration id. But if your app needs authenticated users, you can skip the withCalls() method altogether, and decide when a device is allowed to receive calls. This is easily done by invoking, anytime (for example, when the user of your app has successfully logged in), the method:

MobileMessaging.webRTCService?.applicationId = <your webrtc Application Id> // Do not forget to set it once before calling start() method
        MobileMessaging.webRTCService?.start({ result in
            print("Calls process started successfully \(result)")
        })

2. You may also need to stop the calls from being possible at some point (for example, when your user manually logs out). You can do it so by invoking:

 MobileMessaging.webRTCService?.stopService({ result in
            print("Calls were stopped successfully \(result)")
       })

3. You can then call the webrtcService?.start method when the user logs in again.

Taking control over the calls

WebRTCUI is plug-and-play, and you do not need to intercept any part of the logic: it will handle automatically any call and present the UI it needs. But you can become a delegate of the service if you wish so:

    MobileMessaging.webRTCService?.delegate = self

By becoming a MMWebRTCDelegate, you need to implement the following methods:

1. callRegistrationEnded: this method is triggered when the registration for webrtc calls is completed. It will let you know if succeded or there was an error (and its kind). Registration may fail due to network or configuration problems. You can check the nature of the error to decide if a retry is needed (otherwise, your app won't be able to receive or trigger any call). A further description of any problem will also appear as a console debug log.

2. callUnregistrationEnded: this method is triggered when an unregistration for webrtc calls is completed (the process of asking to stop receiving calls). Same as above, you can interpret the result and act appropiately.

3. inboundCallEstablished: This method will be triggered when a webrtc call is being received. You can then present our default UI (as seen below), or present a UI of your own:

if let callController = MobileMessaging.webRTCService?.getInboundCallController(
                incoming: applicationCall, establishedEvent: callEstablishedEvent) {
                PIPKit.show(with: callController) // This allows you to use the picture-on-picture/maximising-minimising feature.
    }

Customising the calls UI

The UI for interacting with the calls is important. For this reason, we allow you to use your own, build on top of ours, or customise easily the provided UI within the SDK. The WebRTCUI service has a settings variable where you can define all colours, icons and even sounds of the interface:

        MobileMessaging.webRTCService?.settings.inboundCallSoundFileName = "MMInboundCall.wav" // filename for inbound audio file that must exist in your project
        // example on overwritting a color directly
        MobileMessaging.webRTCService?.settings.backgroundColor = .darkGray
        // example on overwritting a sound (wav or mp3 must be in your main bundle)
        MobileMessaging.webRTCService?.settings.soundEndCall = NSDataAsset(name: "phone-ringing-sound")
        // example on overwritting an icon (file must be in your main bundle)
        MobileMessaging.webRTCService?.settings.iconAvatar = UIImage(named: "icon-user-border")
        // example on seting up UI colors from a dictionary
        let colorConfig = [
            "rtc_ui_pulse_stroke": "#ffaaaa",
            "rtc_ui_error": "#ff0033",
            "rtc_ui_primary": "#55ff66",
            "rtc_ui_color_foreground": "#ccffff",
            "rtc_ui_color_text_secondary": "#ffccdd",
            "rtc_ui_color_background": "#123456",
            "rtc_ui_color_overlay_background": "#234567",
            "rtc_ui_color_alert_background": "#987654"]
        MobileMessaging.webRTCService?.settings.configureWith(rawConfig: colorConfig)

Check the whole list of possible options in the class MMWebRTCSettings.

Troubleshooting

1. Q: "When invoking call start and stop methods for restarting/pausing the WebRTC service, it has no immediate effect. Why?".

A: It is very common, by the async nature of WebRTC, that these methods suffer a latency of around 20 to 30 seconds in wort case scenarios, even if their completion return "success". This cannot be avoid it.

2. Q: "The ringing sounds lasts only few seconds, then it becomes quiet or decreases its volume, even if the user did not hang up. Why?".

A: There is feature in iPhone, called Attention Aware, under Face ID & Passcode settings, in which the phone detects your face and silent the ringing. User needs to manually disabled it so this behaviour stops.

3. Q: "I am not receiving a call, that I know is being triggered by other end. Why?"

A: There is a wide range of reasons for a call failing to ring in client's side. Some are:

• Your APNS certificate is not the same in your Mobile Push App and the WebRTC App in Customer Portal, or your certificates are expired, or do not match the enviroment you are using (sandboxing vs production). You will need to recheck your setup in Apple Developer/App Profiles, Xcode and Costumer Portal.
• User has "Do not disturb" mode enabled.
• You app did not handled push registration properly, or someone in your team with management access in Infobip's Customer Portal changed something it should have not changed. As registrations rely on a valid installation data, this problems are usually fixable by uninstalling/reinstalling the app.
• Something else is wrong. Usually, an error explaining the reason in the console should be enough to find the root cause. If there are no logs, you may need to edit the log levels in Mobile Messaging SDK with MobileMessaging.logger = MMDefaultLogger(). The logs, and comparing your own app with the Chat Example project, should be enough. It not, please contact support for further help.