close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Using the Vonage Video API iOS SDK in applications running in the background state

iOS supports multitasking for all apps, however there are a few steps a developer must go through in order to get the OpenTok iOS SDK to work well with different app states. This document covers a set of practices we have found work well with most OpenTok apps. However it is not a substitute for reading through the Apple documentation on the subject — specifically the sections on "Strategies for Handling App State Transitions," "Background Execution," and "Tips for Developing a VoIP App". Although Apple does not consider most OpenTok apps to be VoIP apps, the content on configuring audio sessions and socket configuration is relevant and useful for understanding this document.

Quick start — setting app permissions

In the Info.plist file for your app, set up the background mode permissions as described in the Apple documentation for creating VoIP apps. The key is UIBackgroundModes. Do add the audio value to this dictionary. Do not add voip to this dictionary. We have seen applications rejected from the App Store specifically for the use of the voip flag, so it is important not to skip this step.

There is also a UI for setting app background modes in XCode 5. Under the app build settings, open the "Capabilities" tab. In this tab, turn on "Background Modes" and set the "Audio and AirPlay" checkbox to set the audio background mode, just as in the method for editing Info.plist, above. For completeness, we describe both methods, but the results are identical — you only need to use one of the methods.

What OpenTok can (and cannot) do in the background

Using the OpenTok SDK, an app can do each of the following while in the background state:

An app can resume using the camera as soon as the app returns to the active state.

However, apps cannot do the following while in the background state:

Active OpenTok Sessions in the Background

The configuration described above allows apps to run an active OpenTok session even while the app is in the background, presumably as a result of the end-user pressing the home button, locking the screen, or opening URL content in another process. The audio permission allows the app process to stay unsuspended while in the background, if an audio session is active. This means that audio capturing and rendering can continue in your OpenTok session, as long as another process does not request audio resources.

When correctly configured, iOS provides an indicator that your app is running in the background with an active audio session. This is seen as a red background of the status bar, as well as an additional bar indicating the name of the app holding the active audio session — in this case, your app.

The voip option of the background mode is meant for sustaining long-lived signaling connections to an application server. If your app needs to be notified for application events, we recommend using Apple Push Notifications with your application server to wake the app and conduct a workflow. In our testing, we found that the extra overhead of maintaining an active socket with OpenTok was both too expensive from an energy-consumption perspective and too unreliable to guarantee service. For this reason, we are recommending that app developers not request this permission, unless a long-lived socket is being provided by an implementation other than the OpenTok SDK. Additionally, the App Store submission guidelines call for rejection of apps that needlessly request this permission.

Losing Control

Incoming phone and FaceTime calls are likely the first events you will see that completely interrupt your application. When this happens, your app will be suspended, regardless of whether there is an active audio session.

If your app is suspended because the audio session yielded to another process, there is no need for additional logic to handle this. If the app is suspended for a long period of time, the connection to the OpenTok session will end. Other clients connected to the session will receive connectionDestroyed events for the device connection, and an eventual cleanup will be necessary once the app is not suspended. As long as your controller is processing the error and disconnected delegate events for the session, this should be no different from a voluntary, or any other, disconnect workflow. Clients may reconnect as soon as the disconnect cleanup is processed.