Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs
Visit the Vonage API Developer PortalThis topic addresses considerations when developing for an iOS device:
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.
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.
Using the OpenTok SDK, an app can do each of the following while in the background state:
OTPublisher.publishAudio property to YES is allowed.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:
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.
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.
For more information, see: