Background State

iOS supports multitasking for all apps, however there are a few steps a developer must go through in order to get the Vonage Video iOS SDK to work well with different app states. This document covers a set of practices we have found work well with most Vonage Video 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 Vonage Video 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

To have the app keep recording audio in the background, select the app’s target in Xcode and select the Signing & Capabilities tab. Then Click the + Capability button and add the Background Modes capability to the project. Then select the Audio, Airplay, and Picture in Picture option. This setting will also prevent the app from transitioning to a suspended state while playing and recording audio in the background.

If your app needs high priority push notifications that wake up the app for incoming calls, using the native phone app UI, or be notified about hold events, select the Voice over IP capability in XCode.

What Vonage Video can (and cannot) do in the background

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

  • Keep a session active.
  • Sustain an audio-only session.
  • Set audio/video flags for publishers and subscribers. For example, setting the OTPublisher.publishAudio property to YES is allowed.
  • Publish with a custom video capture implementation that does not acquire the camera (for example, publishing from a file or synthesized video source).

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:

  • Use the camera as a video source for a publisher.
  • Set up new views with video from streams.
  • Keep an active audio session if a phone or FaceTime call is received.
  • Prevent other apps from acquiring system audio resources.
  • Maintain a connection to a session without an active publisher or subscriber.

Active Sessions in the Background

The configuration described above allows apps to run an active 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 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 Voice over IP capability is meant for sustaining long-lived signaling connections to an application server.

If you select the Voice over IP option in the XCode Capabilities section, your app should implement features that justify the capability, otherwise the App Store review may reject your app. This capability should not be used for keeping the app running in the background for other reasons not related to audio or video communications.

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. If your app implements incoming calls we recommend using the VoIP push notifications.

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